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Preface 


WHY THIS BOOK 


Multimedia Presentation Manager/2 or MMPM/2 first shipped as a standalone 
product in 1992 for use on OS/2 2.0. The second release shipped as an integrat¬ 
ed part of OS/2 2.1 in 1993. It is highly regarded by the industry as an excel¬ 
lent multimedia application platform. It has won numerous trade press and 
conference awards. With this extension to OS/2 being mature, in fact multime¬ 
dia itself becoming mainstream, there are programming concepts that are not 
obvious to the normal OS/2 or Presentation Manager programmer. This book 
gives insight, tips and techniques, and samples on MMPM/2 application devel¬ 
opment. It also describes the uses of multimedia for general Presentation 
Manager applications. This book provides programming details into MMPM/2 
programming not found in the MMPM/2 toolkit manuals. 


WHO THIS BOOK IS FOR? 


This book is for anyone who wants to learn to develop OS/2 multimedia appli¬ 
cations using MMPM/2. It provides the overall basics of MMPM/2 and multi- 
media in general. In addition to the basics of MMPM/2 it also gives detailed 
samples for commonly used functions. Since multimedia is becoming a basic 
operating system technology with unlimited benefits to application developers, 
it is very important that application developers have expert advise on to how to 
develop these applications. The benefits are making applications more usable 
by including more of our senses; sight and sound. 
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This book is also for those who are just evaluating or using MMPM/2 and want 
a better understanding of its key features. It gives details on how to utilized 
audio and video in OS/2 applications for more effective and appealing 
applications. 


FINAL WORD 


This book was written based on information from a variety of sources. The first 
and most important source is from the authors’ experience and expertise on 
MMPM/2. The second source of information is from MMPM/2 application devel¬ 
opers and system testers of MMPM/2. Third is from other MMPM/2 literature 
such as the MMPM/2 toolkit, IBM MMPM/2 Redbooks and numerous MMPM/2 
articles written by members of the MMPM/2 development team. Finally appli¬ 
cation programming tips and techniques, performance tips, programming 
errors, and general programming samples from both internal and external 
forums and bulletin boards. All of this information has be formulated into what 
we believe is a MMPM/2 application programming guide that MMPM/2 devel¬ 
opers will find invaluable. 


ABOUT THE AUTHORS 


Bill Lawton and Brad Noe have been part of the MMPM/2 development team 
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Windows® Multimedia Extensions running under WinOS2®. 

Bill Lawton can be reached on Internet at lawton@vnet.ibm.com. Marcelo 
Lopez can be reached at marcelol@gate.net. Brad Noe can be reached on 
Internet at bnoe@vnet.ibm.com. 


ACKNOWLEDGMENTS 


This book could not have been written without the help of the MMPM/2 devel¬ 
opment team providing technical input and support. We wish to thank Linden 
deCarmo, Garry Lewis, Eric Snell, and Warner Sharp for reviewing sections of 
this book for technical completeness. We would also like to thank John Parsons 
and Gary Allran for some of the system diagrams used throughout the book. 



Introduction 


WHAT IS MULTIMEDIA? 


Multimedia, roughly translated is: “The way or form to convey information via 
the combination of several forms of communication.” While this definition 
might seem too complex at first, it definitely expresses succinctly what multi- 
media is all about. Newspaper, radio, and books are all examples of communi¬ 
cations media, but none of them is an example of multimedia. The reason for 
this is that these media all employ only one form of communication; or rather, 
only one of the human senses is required to perceive and gather the informa¬ 
tion being presented. Television, movies, and even video games, in a crude 
sense, are more familiar forms of multimedia. Any inquiry as to what multime¬ 
dia is, unfortunately, is more than likely to illicit a multitude of widely diverse 
answers from those that have some idea of what it is, and blank stares from 
the rest of the general public. 

Invariably multimedia means different things when used in the differing 
contexts of the various disciplines which utilize the technologies behind it. 
Educators call upon multimedia to provide new methods and mechanisms to 
convey instructional material to students, thus presenting the study material 
in a more meaningful and comprehensible way. Salespeople see multimedia as 
a way to ease the information glut that is usually involved with making a sales 
presentation, without losing the client in the process. While to say that 100% of 
all commercial recordings today were done on totally digital audio equipment 
without the aid of computers would be incorrect, that actual number, could be 
“guesstimated” at around 99.9%. Musicians use both digital waveaudio record¬ 
ings and MIDI (Musical Instrument Digital Interface) to control entire series of 
instruments, and in some cases entire orchestral arrangements. Almost all 
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industries dealing with the aural and visual senses have or will be affected by 
the end of this century. 

Today, however, multimedia, in a colloquial sense, is more readily associated 
with personal computers. Specifically, systems equipped with such hardware 
devices, such as sound boards, video graphics accelerators, digital video 
recorder/players, and CD-ROM drives (for example, Sound Blaster SBPro, 
Matrox MGA®, Jovian VIA®, and NEC Intersect® CD-ROM). These systems 
provide specific features which facilitate both the creation and presentation of 
multimedia form information, more commonly referred to as content. 
Obviously, that software can present that content in a coherent, and even 
pleasant manner to the user. Multimedia content can include animation and 
still graphics, text, sounds, digital video, and music. The coming together of 
these and other mediums of conveying information, when adjoined, are at the 
heart of what multimedia is today and what it will become in the future. 

So what about the future of multimedia? One of the major obstacles facing 
those who have a financial stake in the future of multimedia is indeed the 
human-computer interface itself. Even today, with object-oriented interfaces, 
such as the Workplace Shell, there is yet a long way to go to reach a more nat¬ 
ural interaction between human and computer. Many believe that multimedia, 
in, and of itself, is one of the keys to breaking through the barriers of 
human/computer interfacing, hereafter referred to as natural-computing. 
Given current knowledge on the subject, one could say more accurately that 
multimedia may not be the answer, but it is a piece of the natural-computing 
puzzle itself. Humans are quite diverse, no two people relate to the things 
around them, or process information presented to them in quite the same way. 
Some relate better to information in a disassociates form, and thus allow them¬ 
selves the freedom of putting together the pieces in their own way. With even 
the most basic forms of human communication, presentation is everything 
when trying to get that idea from your mind to that of another person. Here is 
where the real power to multimedia computing lies. The bounds of expression 
in presenting ideas are only limited by one’s imagination, what information to 
present, how to organize that information, and most importantly, how to pre¬ 
sent it. 


WHY MULTIMEDIA? 


The answer to “why multimedia?” is as diverse as the answer to: “What is 
Multimedia?” One answer the authors can provide, however, is that the busi¬ 
ness opportunities in this area of software development are virtually limitless. 
No one can say exactly, what is so special about multimedia today. Perhaps the 
hardware has become affordable to more than just the “hard-core” enthusiast. 
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Maybe the arts and film industry has entered multimedia into the mainstream 
thinking of the public by demonstrating the range of human expression via 
multimedia computer systems. For example, portions of both well-known Walt 
Disney Pictures® film hits, Beauty and the Beast and The Lion King , had 
both the animation and music score generated on multimedia computer sys¬ 
tems. Perhaps, its popularity is due to the fact that more and more attention is 
being paid to multimedia by both the computer industry and public press. 
Articles appear daily about new multimedia-driven software products and ser¬ 
vices. Maybe the NINTENDO® “phenomenon” has popularized multimedia. 
The fact that the home-entertainment industry has become a multi-billion dol¬ 
lar a year juggernaut may be responsible for exposing this generation and the 
next to multimedia, and sensitizing the public to what computers can truly do. 
No longer can the concept of “ordering” a computer to perform some task, sim¬ 
ple or complex, be reserved to the likes of science fiction series or films like 
Star Trek. Such capabilities are not only within the realm of possibility, they 
have progressed to the point where consumers actually have a variety of soft¬ 
ware from which to choose. 

One thing is certain, more and more PC manufacturers, capitalizing on all 
this furor, are not only offering “specialty” systems with sound cards, and such, 
but are introducing whole lines of computers built around the multimedia con¬ 
cept. Obviously, to sell all this hardware, software must be availabile to capi¬ 
talize its capabilities. During the time when the first “multimedia” hardware 
became available for PCs, users had to deal with the problem of with what or 
how to combine all these various types and forms of hardware with one com¬ 
mon programming interface between them. 

Many pioneering developers found themselves writing their software to be 
specific to an individual sound card’s features, or, in some instances, even spe¬ 
cific hardware platforms that had even a hint of multimedia facilities, such as 
Commodore 64, with its Sound Interface Device (SID), that allowed for audio 
four-voice polyphony (the ability to create more than one tone at a time). 
Amother such system is the Commodore Amiga®, which has separate coproces¬ 
sors, one for use in the recording and playback of audio and another to facili¬ 
tate the playback of video—and even hardware text to speech. Developers also 
had to develop their own techniques for software-based capture/recording and 
playback of video and audio. As has been the norm with multimedia since the 
beginning of personal computers as an industry, game developers have fasci¬ 
nated us all by exploiting the capabilities of any hardware system. Game 
developers chose to develop private interfaces for all the “core” hardware. For 
example, Adlib® distributed one of the early sound cards available for the PC, 
the Creative Labs Sound Blaster was another, and a few “professional” sound 
module synthesizers were created by Yamaha and Roland. Another matter to 
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contend with was the fact that the raw processing power in most PCs up until 
4 or 5 years ago could not handle the data throughput rate necessary for the 
demands of today’s multimedia. The need for a unifying software API and 
enabling platform was apparent as both computers and operating systems 
advanced and evolved. 

In mid to late 1989, IBM and Microsoft made public the first pieces of infor¬ 
mation about a development effort underway at both companies for the cre¬ 
ation of multimedia enabling software for both the OS/2® and Windows® plat¬ 
forms. While the foundation was laid for a common natural-language interface, 
much diversity remained in the underlying architecture of both target operat¬ 
ing systems. This made the actual implementation of each very different. 
Finally, however, an approach to unifying access, control, and management of 
all these new devices was being developed. 


MMPM/2 


Multi(M)edia Presentation Manager/2, or MMPM/2, was designed and devel¬ 
oped by IBM, and it was intended to be the multimedia-enabling system for 
OS/2 2.0 and 2.1 Presentation Manager (referred to as OS/2 PM hereafter). 
This book presents, the various sub-systems of MMPM/2, and the intent is, 
that the reader will gather a working knowledge of how the components them¬ 
selves work, how they interact, and how to best take advantage of the services 
they provide. The ultimate goal is to create multimedia-enabled software. 
MMPM/2 was designed with the goal of becoming more than just a set of func¬ 
tions a developer could call into, to play a sound file, show a movie, or play an 
audio track off of a CD. MMPM/2 was designed to be a true multimedia devel¬ 
opment system. Its key features are data management, source/destination 
data synchronization, system resource management (memory, hard disk stor¬ 
age), and handling of such complex tasks as run-time event notification. 

Even if a software developer has a clear idea of what is to be presented, has 
the data to present, and knows how to organize the presentation itself; a clear 
understanding of how to design a multimedia-centric application differs a bit 
from “normal” procedural, or even object-oriented, programs. The “how-to” and 
“what-to” of designing multimedia applications, and how to organize or present 
the multimedia data will be provided. The actual “how” of what to do is up to 
the programmer, but we will present guides, for where a developer may find 
the most help in going about his or her development. 
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MCI (AND WE DO NOT MEAN THE PHONE COMPANY) 


One of the single, most important concepts that has developed from the work 
that was done at IBM and Microsoft, is the creation of a singular natural lan¬ 
guage-based, textual, command interface. This interface, called the Media 
Control Interface (MCI), will be covered in this book in detail, and design. 
MCI was commissioned with the unenviable task of providing a consistent, 
coherent form of communication between the programmer, and the multimedia 
devices or service being employed. Given the variety of devices in question, a 
categorization of these devices had to be developed to maintain the coherency 
in the interface. For instance, while some commands, such as an open or close 
are common to all devices, some commands such as eject or lock were unique 
to one device or one type of device. Essentially, the MCI is an interface where¬ 
upon some level of control over multimedia devices could be done in a way that 
even a non-programmer could understand. 

To facilitate the classification of devices, two basic classes of devices were 
created, simple and compound devices. “Simple device” means just that, a 
device that requires no data element on which to operate. An example of a sim¬ 
ple device is the cdaudio device which operates atomically on the media of the 
CD as a whole and does not require the user to specify any specific file or 
buffer. “Compound devices” are that class of device, which DO require a data 
element on which to operate. While the cdaudio device has no data element, 
because the type of media on which it operates can be thought of implicitly 
being its data element, the waveaudio device requires either a file, an 
element within a compound (or bundle) file, or a memory buffer on which to 
operate. An example of a compound device would be a sound card, where both 
waveform audio playback and recording are supported, and, possibly, MIDI 
playback is supported as well. 

The MCI provides further breakdown of these devices into logical classifica¬ 
tions with more commonly recognized audio/video equipment used today. For 
example, some MCI logical devices are: Speaker, Microphone, Amplifier/Mixer 
or AmpMixer, Digital Audio, etc. MCI Commands are broken up in several cat¬ 
egories: System, Required, Basic, and Device-specific commands. System 
commands are those that operate on the system as a whole. For instance, if the 
following command is sent to the MCI: “mastervolume query volume,” the 
reply will be the current system volume setting. Required commands are those 
commands which are necessary even to interact with any given device, and 
which are recognized by all MMPM/2 devices. For example, “open 
waveaudio” opens the waveaudio device and returns an instance of this 
device which can be used to refer to it later. The open statement is one of the 
required commands because to acquire access to a specific device, it must be 
explicitly opened. Basic commands are those commands which, while media 
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type-specific, are also used in common with multiple devices, and are therefore 
considered to be basic to the operation of these devices. “Load waveaudio 
cuckoo.wav” indicates that the data file “cuckoo.wav” should be loaded and 
prepared for use by the waveaudio device. The load command is basic because 
it is a common operation present with all compound devices. The device-specif¬ 
ic commands fall into their own categories by logical device type, and for each 
variation, these apply to only that device for which they are meant. For 
instance, to send MCI the following command, “set waveaudio tempo 120,” 
would be an invalid command, because it commands the waveaudio device to 
perform an operation that does not apply to it. Replace the “waveaudio” in the 
command with “sequencer,” and it works, because the “tempo” keyword 
applies specifically to the MIDI device. The number of variations are quite 
numerous, and cannot possibly be explored here. 


MMIO—HOW DO I MANAGE ALL THIS DATA ??! 

While MCI facilitates the creation of multimedia applications, it is by no 
means the only star of MMPM/2’s various components. Multimedia data can 
rival the size and content of even the largest of databases. Consider that to 
store a single minute of uncompressed CD-quality, stereo audio, requires over 
80 megabytes of storage space. How do you manage the sheer volume of data 
required? The solution developed by IBM and Microsoft was to design a subsys¬ 
tem to provide facilities to help manage and organize such large volumes of 
data. That sub-system was named Multimedia Input/Output, or MMIO, for 
short. MMIO employs the use of common file formats to encapsulate various 
forms of multimedia data. Consider two files with extensions of “.DAT.” 
Without some formalized way of determining the data type of both these files, 
the programmer would be almost lost in trying to determine what the actual 
content of each file was. One of these formalized data formats is Resource 
Interchange File Format (RIFF), an extension to a file format (called 
Interchange File Format, or (IFF) proposal. Originally IFF was produced by 
the game developer, Electronic Arts, in 1985, when it produced games for what 
many have called the first true multimedia computer system, the Commodore 
Amiga. What IFF proposed was a file format whereby the content of a file could 
be determined in a structured and consistent manner. Just what can be accom¬ 
plished by organizing your multimedia content utilizing this file format will be 
covered in greater detail later in this book. MMIO also allows for the extension 
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of its services to encompass not only other data file formats, but various stor¬ 
age types as well. While MMIO is not tied to RIFF, it is the standard data stor¬ 
age format supported by MMPM/2 as it ships today. 


MOTION MULTIMEDIA 


An additional type of multimedia “device” was added, in the vl.l release of the 
MMPM/2 software: Software Motion Video. With the introduction of this com¬ 
pound “device,” the amalgam of digitized images, laid out in the form of a 
“movie” along with an associated, synchronized audio track, multimedia soft¬ 
ware can do more than simply present visual information. Software Motion 
Video (SMV) provides a mechanism whereby the developer can express almost 
any idea or concept. SMV, and the various software components that support 
it, provide for support of various display modes, presentation window size and 
color depth, as well as data file formats (IBM’s own Ultimotion, and Intel’s 
Indeo). Just taking a pre-canned movie file and utilizing it is not enough, 
although a market is developing for providing just such a product; in many 
instances; however, recording one’s own video is absolutely necessary. 

Recording SMV content can almost be likened to the art of actual film pro¬ 
duction because the developer is putting together two streams of data that in 
and of their own can convey a message to the user when played back. 
Truthfully, however, listening to the soundtrack of the Apollo 11 landing on 
the moon cannot be as moving as seeing it happen while hearing what the 
astronauts were saying as it happened. The SMV recording process requires 
consideration of many different variables: what the actual content will be, and 
how the data will be organized in the final output file, to name a few. Things 
such as data playback rates, color modes, etc. can make all the difference; 
because of all this, the programmer must literally develop some “artistic skill” 
in this sort of product process. Many software development companies go so far 
as to employ actual film professionals and artists to help them put together the 
right content to provide or present. 

What to present, and how to lay it out visually, are not the only concerns. 
How to store all this data is a task of what could be considered monumental 
proportions. For instance, in the previous description of the data resource 
requirements of a particular type of waveform audio file, the storage require¬ 
ments hovered around 80+ megabytes uncompressed. Consider that a very 
basic movie of similar length could, depending on content (color modes, etc. 
mentioned before), require about 500 megabytes to store. That amount of data- 
space is enough to rival, if not dwarf, any other file type a developer might ever 
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use. The product to do SMV authoring is called OS/2 Video IN®, and it is avail¬ 
able in the Bonus Pack of OS/2 Warp for the creation of SMV content. The use 
of various pieces of the Video IN® and its associated development toolkit will be 
covered as well. 


LET US PLAY SOME MUSIC 


Recording and playing back digital audio, or waveaudio, can be one of the 
most useful and perplexing things a developer can use his or her software for. 
Our intention is to make this process not just more bearable, but more natural 
and as much an integral part of designing an application as any other part of 
the development process. While simply adding a little jingle or tune to some 
visual cue may be all that is desired, developers have no reason not to consider 
how to make use of even the simplest of MMPM/2’s waveaudio capabilities. For 
instance, consider one important question: Space vs. Quality, “Do I sacrifice 
audio playback quality to save storage on the media where the data will be 
stored?” These and other questions are the considerations that all program¬ 
mers face when dealing with multimedia in general. The section discussing 
this topic provides the programmer with the necessary background information 
and with examples of how to integrate and manipulate waveaudio from within 
an OS/2 PM application. 


MULTIMEDIA GADGETRY 


As a developer, even with all the content in the world, the visual layout of the 
application and what types of controls the users have at their disposal can 
make all the difference in how the software is judged. For this purpose, 
MMPM/2 provides a standardized set of “multimedia controls” which can help 
the developer give the user access to the content in a way that the may feel 
more comfortable or more intuitive. Again, the premise that how information is 
presented carries as much weight as the information itself is vital to the suc¬ 
cess of any development efforts. These controls, called secondary windows, cir¬ 
cular sliders, and graphic buttons, not only make for good presentation, they 
also help in the creation of a more consistent and intuitive human-centered 
interface. Since these controls are already in use throughout all of MMPM/2, 
the likelihood that the user may have some familiarity with them will make 
the application easier to use. 

How these controls are used is up to the programmer; how they behave is 
also primarily under programmer control. How these controls appear is pri- 
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marily up to MMPM/2. If a circular slider (akin to a round volume knob on a 
stereo) is moved clockwise, the arrowed indicator follows that clockwise motion 
along with the motion of the cursor, be it attached to a keyboard or to a mouse. 
Other controls help represent some particular activity that the application is 
performing. The type of control that allows this is called a graphic button, or 
in the case of our example, an animated graphic button. The animated 
graphic button may be used to cause or represent a state change in the applica¬ 
tion, or a change in some particular feature. It may also be used to indicate 
some ongoing operation within the application. This is accomplished by playing 
back an animation based on a series of simple bitmaps. 


PUTTING IT TOGETHER 


How a multimedia application is built, how the pieces fit together, is very 
important. This, and a discussion of performance, how to get the most out of 
the effort placed into the development effort, are both essential. How all the 
pieces fit together is not the only thing that is important, how they interact is 
also very important. Make sure that when utilizing multimedia components in 
your application they do not inhibit or complicate, any of your other develop¬ 
ment work. Integrating multimedia components into an application should not 
make you sacrifice any other necessary functionality. One of the keys to all 
multimedia development is that whatever MMPM/2 support is added inte¬ 
grates into the final product as smoothly and seamlessly as possible. In other 
words, it must function and fit into the overall scheme of the product. It must 
appear to the user to belong as much as any other piece. 

When developing multimedia software, some basic things must always be 
taken into consideration: design and layout of the application, what the neces¬ 
sary data files are, and how to structure it all together. One of the areas many 
developers tend to overlook is programming considerations, which is taking a 
look at the process as a whole, not just at the pieces of the development 
process. How each portion of the application fits with another affects a great 
deal how the overall product is perceived. One of our goals here is to provide 
pieces of information to make the software development process more produc¬ 
tive and less prone to requiring what could be costly updates. For instance, 
taking certain things into account up front can mean significant gains, by help¬ 
ing produce a better product in less time. This mindset will help you create 
software that is not only more user-friendly, but also more maintainable. 

As multimedia deals with utilizing possibly more than one of a human’s 
senses, whatever is done should behave at “human” speed, that is, it should be 
pleasant to “experience” at the least, exciting or attention grabbing at best. To 
do this, the developer must make careful choices for resources vs. time vs. com- 
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plexity. What trade-offs need to be made? Certainly, these decisions ultimately 
lie with the developer, but some rules of thumb and considerations will be pro¬ 
vided to make the decisions more acceptable ones. 

Throughout the book there are examples of how to use MMPM/2 for various 
different purposes are presented. Not only is sample code fragments for per¬ 
forming basic or atomic operations included, but a sample application is includ¬ 
ed as an example of how to utilize multimedia components wisely. The sample 
is intended primarily as a reference to familiarize you with the various pieces 
of the process of multimedia development. Covering one subject too heavily is 
definitely not the intention of this book; better to present all the major topics 
and functionality, and allow readers to decide what pieces best suit their devel¬ 
opment effort. In this application, many important tips and information con¬ 
cerning multimedia development will be provided to give a “how-to” example. 

Within the application, when a multimedia component is used, a short 
explanation of why this component is used will be provided. The authors’ goal 
is to make the multimedia development process under OS/2 as straightforward 
and as easy as possible. 


GIVING YOUR APPLICATION A TUNE UP 


Just as with a car, any application you write has to have some “tuning-up” or 
performance improvement done to it. Code never runs as quickly or as effi¬ 
ciently as programmers and users would like. The chapter on tuning the appli¬ 
cation not only covers how to tune the environment the application runs on, 
but also the “whats,” “hows,” and “whens” of tuning the design and implement¬ 
ing the multimedia application under MMPM/2. Tips and helpful insight, not 
just into the process of developing your software, but into how these things will 
benefit your application, and ultimately translate into more user-accessible 
software are provided. 

The performance of any application is of utmost importance. No one wants 
to buy software that’s hard to use, too slow to make a user productive, or down¬ 
right boring! 


LOOK AT ALL THE "TOYS" 


Toy is a term that in the computer world refers to any new piece of hardware a 
developer acquires, and multimedia hardware is no exception. With all the new 
hardware constantly being introduced into the market, it is virtually impossi¬ 
ble to provide a totally complete list of the multimedia hardware products 
available today, but in this book we include most of the major hardware being 



Introduction 11 


supported today, what the features are, and how they are exploited under 
MMPM/2. Having knowledge about what multimedia-oriented hardware is 
available for the developer to use is not enough. A developer needs to have a 
good grasp of what capabilities the hardware provides. For instance, certain 
data types, such as SMV, requires a certain amount of sustained data transfer 
rate by whatever media is storing and transporting the data to the system. A 
knowledge of the hardware necessary to author and present multimedia is 
therefore crucial to the process of development. 

What type of features are really necessary for the multimedia data produc¬ 
tion process? Another age old question: “What are the product requirements for 
the user to have to use my software?” Microsoft presented to the development 
community what such requirements should be in the MPC and MPC2 stan¬ 
dards, but what does it mean to be MPC, and is that all that’s really needed? 
This book offers a glimpse at the hardware of today, and what it points to as 
the capabilities and possibilities of the hardware of tomorrow, and also pro¬ 
vides a good indicator of where software support itself is headed. 


WHAT DO I USE TO BUILD MULTIMEDIA APPLICATIONS UNDER MMPM/2? 


Given that the focus of this book is multimedia under OS/2, or MMPM/2, it is 
assumed that the reader has a good background of programming under OS/2, 
the Presentation Manager environment, and its programming tools. The vari¬ 
ety of choices of programming tools is wider than one would expect. While the 
MMPM/2 interfaces are primarily developed for use by the “C” programming 
language, that is by no means the only choice available to a software developer. 
Other choices are REXX, as well as the 16-bit and 32-bit “C” interfaces. All the 
programming examples provided within this book are in “C” using 32-bit code. 

Other than procedural programming languages, developers have choices of 
what tools to use. Other programming products are available to perform, or 
facilitate multimedia development. Do you even need a “standard program¬ 
ming language” for doing multimedia software development? The answer is no, 
as is demonstrated later in this book. Software development is akin to the 
process of building a house or a structure. The choice of tools, and materials 
affect the overall outcome. The first step is in deciding what you wish to pre¬ 
sent, and what you wish to enhance by the inclusion of multimedia support. 

What tool, or tools, should be used? What tools to use in many instances 
depends upon what kind of application you wish to write. A growing list and 
variety of “authoring” products can be used for the creation of either a multi- 
media presentation or even a whole application. The function and features of 
some of these products will be presented, along with an indication of what sort 
of multimedia development each product might more adequately suit. 
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QUICK REFERENCE 


What we call a “QuickRef” or quick reference will be provided, along with a 
glossary of the terms used throughout the book, and specific information is pro¬ 
vided about the MCI, MMIO APIs, and the REXX interfaces mentioned previ¬ 
ously. Also, listed are the APIs for utilizing the multimedia “standard” con¬ 
trols, and the messages used to communicate with these controls. This refer¬ 
ence is not meant to supplant the documentation provided with the MMPM/2 
and Video IN toolkits, but it is intended to be a place to reference quickly 
something of importance. The QuickRef also contains any notes the authors 
may have gathered in the preparation of this book. 


THE CATCH 


We will begin by covering how MMPM/2 itself is architected, what its major 
components are, how they are connected, and, in an overall sense, how the sys¬ 
tem actually works. We do not cover every single detail about MMPM/2, the 
material we provide fulfills both items mentioned above. An overview of the 
streaming sub-system is presented along with a description of how the other 
streaming components, stream handlers, communicate. 

To make multimedia more accessible and more easily manageable, there’s 
the Media Control Interface or MCI. To use MCI effectively, you need to under¬ 
stand what its facilities are, how it manages devices, and how it organizes the 
multimedia “orchestra.” The chapter on MCI does that, presenting not just 
APIs, but mechanism behind them, and how requests are handled, as well as, 
how to interact with other applications in the MMPM/2 environment and share 
resources. 

Managing multimedia content can be a daunting proposition. The 
Multimedia Input/Output subsystem, or MMIO, is utilized throughout 
MMPM/2 to handle the file and storage specifics of multimedia data. We cover 
some basics of audio theory and how it relates to the authoring of content. We 
discuss how to start making use of the waveaudio device to playback and 
record audio data simply and quickly. We also look at how to use the MIDI 
device capabilities of MMPM/2 and present an overview of the AmpMixer 
device and how to use some of its basic functions. We go into the subject of con¬ 
nectors, what they are for, who manages them, and how to attach and discon¬ 
nect them. We even look into the mysterious playlist and show how it can be 
used quickly and simply. 

With SMV we go into the movie business, by showing you how to make use 
of the newest and most exciting of features present in MMPM/2. Why SMV is 
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exciting, because, just as in the days of early TV, the public is currently being 
exposed to this new medium, communication by computer. We cover the tech¬ 
nology and architecture behind MMPM/2’s SMV showing what the video data 
types and compression schemes are. Fundamentals about video authoring, 
insights into the video capture and playback process, how to handle the volume 
of data, and how to blend audio and video data into one to create stunning pre¬ 
sentations are covered in this chapter. 

To get you started in the process of development, we provide a few samples 
to get you underway. We show you how the various pieces of the application fit 
together with support for MMPM/2 and give some information on what type of 
development environment can be set up to build your applications. We also go 
into how to best take advantage of the design and architecture of MMPM/2 to 
improve the overall performance of the multimedia application. 

Finally, we also provide what we consider a useful “in-one-place” reference 
on MMPM/2’s main APIs, commands, and data structures. A glossary of all the 
new terms and phrases to which you may need to refer is provided at the end of 
the book. 

The programming advice given in this book will help you develop multime¬ 
dia applications for OS/2, and also for OS/2 for the PowerPC. OS/2 for the 
PowerPC applications are 32-bit OS/2 applications recompiled for the 
PowerPC. All of the application programming interfaces presented in this book 
will be available for OS/2 for the PowerPC. Continue to watch the trade press 
for more details on OS/2 for the PowerPC or contact IBM for more information. 





How MMPM/2 Works 


INTRODUCTION 


Multimedia Presentation Manager/2 or MMPM/2 was designed and developed 
as an extension to OS/2 2.0, 2.1 and Warp. It takes advantage of the preemp¬ 
tive multitasking and 32-bit flat memory model features of OS/2. These fea¬ 
tures of the operating system are essential to the presentation of multimedia 
data. Multimedia, as its name implies, handles the presentation of various dif¬ 
ferent media to the user. This presentation of media usually needs to occur in 
synchronization with various media requiring near-real-time, if not real-time, 
performance. The other distinguishing feature about multimedia is the amount 
of data multimedia can manage. Multimedia audio and video data are on the 
order of megabytes vs. kilobytes for traditional data, even when the data is 
compressed. The 32-bit flat addressing memory model of OS/2 allows for the 
manipulation of data of this size. 


SYSTEM ARCHITECTURE 


The system architecture is shown in Figure 2-1. This figure shows the various 
subsystems and their pluggable components. Notice that most applications 
program to the Media Control Interface (MCI) or the Multimedia Input/ 
Output (MMIO), but all three subsystems shown have public Application 
Programming Interfaces or APIs. 
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Figure 2-1. MMPM/2 System Architecture 


As you can see from this figure, applications mainly use three interfaces; 
MCI, MMIO, and multimedia controls. These interfaces provide a consistent 
device-independent, data-independent programming model. Applications view 
the MMPM/2 multimedia devices as abstractions of multimedia devices with 
which they are familiar, such as the audio device. The operations performed on 
these abstract devices are very much like those used on a VCR, videodisc, or 
home stereo system. The abstraction of multimedia devices with their familiar 
commands provide an intuitive multimedia programming model for application 
developers and users. 

Although application developers need not concern themselves with the over¬ 
all MMPM/2 system architecture, a description of the architecture is provided 
for completeness. The MMPM/2 system is broken down into three subsystems 
and a set of common user interface controls. Each subsystem has a manager 
and a set of “pluggable” components. Depending upon the MMPM/2 device to 
which the application is programming, one or more of the subsystems are used. 
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Most applications are aware of only the MCI subsystem. The other two subsys¬ 
tems, Multimedia Input/Output (MMIO) and Synchronization/Streaming 
(SSM), are mainly used by the lower level components of MMPM/2. 
Applications can program to the MMIO subsystem to handle specialized data 
or file requirements. The SSM subsystem is mainly for subsystem developers 
providing data streaming components. The multimedia controls provide a con¬ 
sistent set of multimedia user interface controls for Presentation Manager 
applications. The following sections describe each of the subsystems in general 
terms. 


COMPONENTS 

Media Control Interface (MCI) 

The Media Control Interface provides applications with a logical view of the 
multimedia devices available in the system. These logical multimedia devices 
range from digital audio devices to external laserdisc devices. The set of opera¬ 
tions, or MCI messages, performed on these logical devices are, for the most 
part, common across all logical MMPM/2 multimedia devices. These commands 
fall into a set of command categories. The categories are: 

• Device control messages 

• Device information/status messages 

• Device setup messages 

• Device synchronization and event notification 

• Device notification messages 

• System control messages 

• Media editing messages 

Refer to the chapter on Using the Media Control Interface for details about 
these message categories. 

All MCI commands and APIs are processed by the Media Device Manager or 
MDM. MDM performs such functions as string command parsing, system com¬ 
mand processing, resource management, and media device message routing. 
Once a media device instance is opened, MDM routes most other commands 
directly to the media device for execution. Certain commands such as acquire, 
release, and close cause MDM to perform resource management on the cur¬ 
rent set of media device instances. 
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Device instances are created by an application using the MCI_OPEN or 
open message. The Media Device Manager interprets these messages and 
sends them to the appropriate Media Control Device or MCD. The MCD will 
create an instance of the multimedia device it is portraying. This logical device 
may be a physical device, or it may be multiple physical devices logically used 
together to give the appearance of a single device. After the media device 
instance has been “opened” other MCI commands can be sent to that device ID. 
The device ID is very similar to a window handle or file handle; it is MMPM/2’s 
unique identifier for that media device instance. 

The processing of MCI messages involves more than just MDM. There are 
three components involved in the processing of most MCI commands. These 
components are: Media Control Drivers (MCD), Vendor Specific Drivers 
(VSD) and Physical Device Drives (PDD). The VSDs and PDDs are not always 
present, but generally they represent the device-specific processing of MCI 
commands. 



Figure 2-2. MCI Command Processing 

The MCDs provide the MMPM/2 specific and common processing of MCI 
commands. Some of these functions include: 

• command notifications 

• device instance maintenance 
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• state management 

• status and capability 

• multimedia I/O control via MMIO 

• data streaming setup and control via SSM 

MMPM/2 comes with a set of MCDs that handle digital audio, MIDI, 
videodisc, digital video, image, CD audio, and CD/XA data and devices. 
Additional MCDs have been developed for DVI video, and overlay video and 
are provided by other IBM products. 

The VSDs provide a device-independent bridge from the MCD to the PDDs. 
This interface allows one MCD per multimedia device type; most supplied by 
IBM. It also implies that adapter manufactures only supply a VSD/PDD pair. 
The VSD interface is extendible to allow for more advanced functions than are 
currently defined. MMPM/2 currently provides for an audio and video capture 
VSD definitions. Additional VSD definitions can be created as new device types 
warrant it. 

The PDDs are the traditional OS/2 device drivers supplied for hardware 
adapters. These PDDs are written to a MMPM/2 (audio and video capture) 
device driver definition. If the devices provide the standard set of functions for 
a particular device type, no VSD needs to be written by the PDD developer. 
Both the audio and video capture DD models define a robust DD interface that 
plugs into the audio and video capture VSDs. This enables audio and video 
capture adapter manufactures to write as little as possible code to provide 
MMPM/2 support for their adapters. Besides the actual function, the PDD 
models provide for MMPM/2 resource management and data streaming. 

MMPM/2 Devices 

MMPM/2 comes with a standard set of multimedia devices. Some of these 
devices require external hardware. These devices are: 

• Waveform Audio 

• MIDI 

• Laserdisc 

• CD Audio 

• CD/XA 

The other multimedia device that comes with MMPM/2 is the digital video 
device. Digital video, or motion video, requires any display subsystem support¬ 
ed by OS/2. Additional MMPM/2 devices such as overlay video, text to speech, 
camera, and others are available through other products or will be coming in a 
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future release of OS/2. The design of MMPM/2 allows for the easy insertion of 
these additional media devices or new media device types. Since multimedia is 
still evolving as a technology, this becomes a very important feature for appli¬ 
cation developers and users. 

Some MMPM/2 devices fit into both the external and internal device cate¬ 
gories. For example, the CD Audio device can play back audio using the digital 
to analog (DAC) converter on the drive. In addition, the CD audio device can be 
used to read the digital audio data and to feed it to an amp mixer device in the 
system. This kind of digital audio transfer is known as streaming. To deter¬ 
mine whether a device can stream, a capability can be sent to the media 
device instance which will determine if it can stream. 

Multimedia Input/Output 

The multimedia input/output subsystem provides a set of file and data services 
for multimedia data. These services isolate applications from the file and data 
dependencies. The MMIO services provide applications with easy access to 
variety of media elements such as digital audio, digital video, images, and 
graphics. MMIO also provides services to access these media elements in vari¬ 
ous file formats or data wrappers such as Resource Interchange File Format 
(RIFF) and Audio Video Interleaved (AVI). These data handlers are called 
MMIO 10 procedures. In addition to accessing data and file formats, MMIO 
also provides for compressors and decompressors or CODECs. These compo¬ 
nents are similar to 10 procedures and are called CODEC procedures. 



Figure 2-3. MMIO Subsystem 
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MMIO procedures provide application access to different file and storage for¬ 
mats. The 10 proc shields the applications from the details of the layout of the 
data in the file or the storage system. Applications communicate with 10 proce¬ 
dures through the MMIO manager. Application messages for an 10 procedure 
are converted by the MMIO manger into one or more messages to a particular 
10 procedure. 

COmpressors/DECompressors or CODECs handle the compression or 
decompression of data. This data can be anything from audio to video to image. 
By providing for these pluggable CODECs, MMPM/2 is very well suited to han¬ 
dling new compression algorithms and shielding this fact from the application. 
A good example of this is the fact that an application can play a movie file and 
not know or care what type of video decompressor is used. The MMIO subsys¬ 
tem provides this information to the digital video subsystem. 

MMIO is used in two ways. The first way is directly by applications. 
Applications can utilize the services of MMIO directly to provide access to mul¬ 
timedia data for converting, browsing, copying, and editing. Applications have 
complete access to all of the 10 procedures and CODEC procedures installed in 
the system. 

The second way MMIO is used is by the other components, mainly the 
Media Control Devices, of the system. For example, when an application wants 
to play an audio file through the MCI interface the waveaudio, Media Control 
Device makes calls to MMIO to determine the right 10 procedure for the audio 
file. The Media Control Device then uses that 10 procedure to read/write the 
audio data. The other way that MMIO is used by MMPM/2 components is 
when a movie file is played or recorded. Movie file formats such as AVI not 
only have a file format but can support different video compression formats. 
Therefore the MMPM/2 system components involved in the playback or record¬ 
ing of an AVI movie makes calls to MMIO to locate the right CODEC to use. 
These components also make calls to that CODEC to compress or decompress 
the video data and to write or read it. 

MMIO, like the rest of MMPM/2, is a very modular extensible subsystem. It 
is very easy to write new 10 procedures and CODEC procedures and to install 
them in the system. 10 procedures and CODEC procedures can be installed 
during runtime or by an installation procedure. The chapter on MMIO discuss¬ 
es 10 procedures and CODEC procedures in detail. 

Synch/Streaming Manager 

The Synch/Streaming Manager (SSM) provides the system wide data stream¬ 
ing and synchronization services. Although the SSM interfaces are available to 
applications, it is the MMPM/2 subsystem components that utilize these ser¬ 
vices. Why are data streaming and synchronization services required by a mul- 
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timedia system? Look at the requirements of multimedia data during playback 
or recording. The first requirement is near real-time or real-time performance. 
Real-time means providing response or delivery based on the requirements 
imposed by an outside process. This outside process might be the authoring 
environment or an end user. In either case the system must provide perfor¬ 
mance and responsiveness to the playback or recording such that these 
processes occur with as little interruption as possible. Once an audio stream of 
data has starting playing or recording, the data streaming must continue with 
very little interruption. If there is much system interruption, the user will 
notice audio breakup. 

Since OS/2 provides a preemptive multitasking scheduler, SSM was 
designed to provide systemwide services for data streaming that provide these 
near real-time characteristics. Media Control Devices do not have to be con¬ 
cerned with implementing these required common functions since MMPM/2 
provides these streaming and synchronization services. It also allows for 
MMPM/2 to take advantage of the operating system functions (current and 
future) to provide the near real-time characteristics. 

SSM provides these streaming services through components known as 
stream handlers. A stream of multimedia data has a source stream handler 
and a target stream handler. The stream handlers negotiate among themselves 
through SSM to agree on the size and number of buffers to use. Once the 
stream is started, the source stream handler requests empty buffers to fill, and 
the target stream handler requests full buffers to empty. Each stream handler 
executes on its own high-priority thread or fast thread independently of the 
rest of the system. These fast threads provide minimal thread dispatch times. 
This fact provides the near real-time streaming performance. The “stream” is 
stopped, paused, flushed, and closed, based on the MCI commands sent to the 
media device instance. The MMPM/2 system comes with a set of file, memory, 
audio, and video stream handlers. 
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Figure 2-4. Streaming Subsystem 

Given this set of systemwide data streaming services, users still need a way 
to tune the data streaming to the characteristics of the particular data. For 
example, high quality audio data has different characteristics and require¬ 
ments than low quality audio data. SSM provides stream protocol control 
blocks (SPCBs) to allow for this tuning. The SPCBs describe the data in data 
streaming terms (buffer size, number of buffers, etc.). A set of SPCBs is provid¬ 
ed and tuned by IBM for a wide range of audio, video, and MIDI data formats. 
SPCBs can also be added and updated by applications or suppliers of new data 
types. This allows the system performance to be tuned for special requirements 
or when new data types need to be added. This is all transparent to applica¬ 
tions and users. 

The other main function of SSM is to provide for an architected method of 
detecting and notifying stream handlers when the stream drifts out of synchro¬ 
nization. Let us explain synchronization before we describe the MMPM/2 
method of synchronization: When two or more data streams are running, such 
as an audio and video stream, the system often requires that they run in syn¬ 
chronization. Users expect to have the audio match the video. This is very 
noticeable when talking about lip synch (the audio matches the lips of a char¬ 
acter in a video). SSM can determine when stream handlers begin to get out of 
synchronization with respect to some master stream handler. When a stream 
handler gets out of synchronization by some tolerance amount, SSM will notify 
that stream handler to get back in synchronization. It is the responsibility of 
the slave stream handlers to adjust their streaming playback rate to that of a 
defined master (audio is usually the master for a movie). Currently the audio 
stream handler can only act as a master and the video stream handler can only 
act as a slave. This streaming architecture allows for additional components to 
provide for the synchronization of non-streaming device (CD and Laserdisc) to 
streaming devices. 
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Figure 2-5. Data Streaming Synchronization 


MULTIMEDIA CONTROLS 


Since multimedia is a new and emerging technology, the user interfaces associ¬ 
ated with it are also new and emerging. MMPM/2 provides three customized 
Presentation Manager controls. These customized user interfaces include sec¬ 
ondary windows, graphic buttons, and circular sliders. These customized user 
interfaces are used by the MMPM/2 applets and are described in detail in the 
Multimedia Secondary Windows and Controls chapter. The secondary windows 
provides for scrollable and sizable windows. The graphic button provides for 
two states and animated push buttons. The circular sliders provide the same 
function as the normal sliders except that are circular and give the impression 
of knobs on a stereo system. These controls provide functions very much like 
normal windows, push buttons, and linear sliders do. 
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PROGRAMMING MODEL 

Application 

The MMPM/2 programming model is an extension to the Presentation 
Manager programming model. It provides a set of APIs, both procedural and 
string, that support a set of messages. The Media Device Manager sends these 
messages to the Media Control Devices. Responses can occur either synchro¬ 
nously or asynchronously depending on a flag sent with the message. If the 
response is asynchronous then a MMPM/2 message MM_MCINOTIFY is sent 
back to the application window queue via the WinPostMsg API. Because of 
this and the fact that resource management messages are also sent to the 
application via WinPostMsg , MMPM/2 applications must be Presentation 
Manager applications. 

APPLICATION 


MainProc() 

{ 

switch(msg) 


{ 

case MM_MCINOTIFY: 

case MM MCIPOSITIONCHANGE: 

} 

} 



mciSendCommand 



mciSendString 


MMPM/2 



MM_MCINOTIFY 

MM_MCIMCICUEPOINT 

MM_MCIPASSDEVICE 

MMJVICIPLAYLISTMESSAGE 

MM_MCIPOSITIONCHANGE 


Figure 2-6. MMPM/2 Message Programming Model 
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Since MMPM/2 applications are extensions to Presentation Managers appli¬ 
cations they have requirements in addition to the normal Presentation 
Manager application requirements. The normal stack requirement for 
Presentation Manager applications is 4k to 8k bytes. MMPM/2 applications 
require between 8k and 16k of stack space, with 32k being the recommended 
size. One tell tale sign of stack problems is a protection exception in the 
MMPMCRTS dynamic link library. If this occurs, increase your application’s 
stack size. 

Since a number of the MMPM/2 functions, such as play and record, take 
long periods of time to complete (seconds, minutes, and even hours), MMPM/2 
applications should be multithreaded. This is very important in order to pro¬ 
vide good system responsiveness to other Presentation Manager messages. A 
good working knowledge of Presentation Manager is vital to create not only 
functional MMPM/2 applications, but also ones that run well in the multitask¬ 
ing operating system of OS/2. 

The MMPM/2 set of media control device messages have two modes of opera¬ 
tion, synchronous and asynchronous. These modes will be discussed in more 
detail in the MCI chapter. Since applications have the choice of which mode 
MCI commands are executed in, it is important to pick the best mode for the 
given MCI command. Commands that generally take long periods of time to 
complete should be used in asynchronous mode. Examples of these commands 
are play, seek, record, rewind, and spin. Commands requiring very little 
processing time should be executed in synchronous mode. Examples of these 
commands are status, info, capability, and set. 

Within the MCI interface there are two forms of sending commands. Both of 
these interfaces are discussed in greater detail in the MCI chapter, but it is 
important to understand from the start the advantages of both. The two APIs 
are mciSendString and mciSendCommand. The mciSendString API is 
referred to as the string interface, and the mciSendCommand interface is 
called the procedural interface. The string interface allows natural ASCII com¬ 
mand strings to be used. These strings are parsed by a string parser that is 
part of the MDM. The parsed strings are then executed by MDM and the 
MCDs. This interface is the preferred interface because it shields the applica¬ 
tion from most device-type dependencies. There are some commands that are 
not available using the string interface, but this set of commands is small, and 
string and procedural commands can be interspersed. 

Subsystem Developers 

It is not within the scope of this book to provide much in the way of subsystem 
development help. Some discussion on the use and the creation of MMIO 10 
procedures and CODEC procedures is given. Very little is discussed about 
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MCD or stream handler development. These topics alone could fill a book. For 
more information on these topics, see the IBM MMPM/2 Toolkit Subsystem 
Development Guide. 


DEVELOPMENT ENVIRONMENT 

Toolkit 


MMPM/2 application developers will need the OS/2 Toolkit , Multimedia 
Presentation Manager Toolkit / 2, and a C compiler ( IBM C Set 12). The 
MMPM/2 toolkit contains all the necessary C programming headers and 
libraries. The MMPM/2 toolkit also contains some sample code highlighting 
various features of the system. The MMPM/2 toolkit comes on a CD ROM disc. 
After the toolkit is installed the directory structure will: 


MM0S2\MMT00LKT\LIB 

\H 

\ INC 

\SAMPLES 

\BITMAPS 

\NEATSTUFF 


Figure 2-7. Toolkit Directory Layout 

The sub-directories contain the following files: 


Sub-directory 

Description 

LIB 

MMPM/2 Library 

H 

MMPM/2 Header files 

INC 

MMPM/2 Assembler include files 

SAMPLES 

MMPM/2 Toolkit Samples 

BITMAPS 

MMPM/2 Small size bitmaps for multimedia controls 

NEATSTUF 

MMPM/2 Toolkit “Use as is” stuff 


Table 2-1. Toolkit Structure 
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The MMPM/2 toolkit installation will update config.sys for LIBPATH, 
BOOK, INCLUDE, and LIB. Once the toolkit is installed, MMPM/2 applica¬ 
tions can be compiled and linked on the developer’s system assuming a compil¬ 
er has been installed. 


Headers 


All of the MMPM/2 public interfaces are available by including the header file 
OS2ME.H in your application’s source files. To access various subsystem pro¬ 
totypes and constants, a set of defines are available: 


Define 

Services 

INCL_MCIOS2 

MCI 

IN CL_MMIOOS2 

MMIO Data and File 

INCL_OS2MM 

Both MCI and MMIO services 

INCLJ3W 

Multimedia Window Controls 

INCL_MIDIOS2 

MIDI Mapper defines 

INCL_CDAUDI02 

CD Audio defines 

INCL_MACHDR 

High level application service (REXX, Macro, etc.) 


Table 2-2. MMPM/2 Programming Defines. 

In version 1.0 of the MMPM/2 toolkit, the header files used WORD and 
DWORD variable type declarations. Version 1.1 and Warp uses type declara¬ 
tions and naming conventions more consistent with the standard OS/2 format. 
The header files defined in release 1.0 are no longer supported. To improve the 
compilation times use the #defines that will include only those header files 
that your application really requires. For example, if the application only 
requires MCI definitions, then define INCL_MCIOS2. 




How MMPM/2 Works 29 


#define 

I NCL_ 

_MCI0S2 

/'k-k-k-k'k'k'k-k'k-k-k'k-k'k-k-k-k'k'k^'k'k-k'k'kicic'k'k'k-k'k'k-k'k'k-k'kic'k'k'k/ 

#define 

I NCL_ 

_MM 100S2 

/* 

Define only those includes 

your C file 

*/ 

#define 

INC L_ 

_0S2MM 

/* 

is going to use. This will 

help speed 

*/ 

#define 

I NCL_ 

_SW 

/* 

up compile time. 


*/ 

#define 

I NCL_ 

_M ID10 S 2 

/* 



*/ 

#define 

I NCL_ 

_CDAUDI02 

/* 



*/ 

#define 

IN C L_ 

_MACHDR 

/******************************************j 

#i nclude 

0S2ME. h 






Figure 2-8. Source Code Header 


Libraries 


To simplify the development of MMPM/2 applications, applications need to link 
to one library, MMPM2.LIB. This contains all the entry points for the MCI, 
MMIO, SSM, and multimedia controls. All of the DLLs required are part of the 
MMPM/2 runtime environment that is part of the OS/2 system. 


MCISTRNG 

Included in the MMPM/2 toolkit is a sample program call MCISTRNG. This 
program allows MCI strings to be entered and sent to MMPM/2. MCISTRNG 
takes the string command entered and makes a mciSendString call. In addi¬ 
tion to making MCI string command calls, it also has a window to monitor the 
notification messages from MMPM/2. These notification messages not only 
include MM_MCINOTIFY messages, they also include all MMPM/2 messages 
sent to applications from MMPM/2. This program can be a very valuable tool in 
learning how to open, manipulate, and close MMPM/2 devices. It can also be 
used as a test tool to test out different sequences of MCI commands. This tool 
was used extensively during the development of MMPM/2 by both the develop¬ 
ment and test teams. 
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NEATSTUF 


The NEATSTUF directory contains two tools that are useful for testing and 
working with audio files. The first one is P2STRING. This is a testing tool that 
can help automate the testing of particular MCI string command sequences. 
This tool allows for multi-threaded and multiple processes. The output from a 
particular “script” is logged. 

The second tool is WAVEDOC. This tool lets the user manipulate the char¬ 
acteristics of a waveform audio file. Characteristics such as sampling rate, vol¬ 
ume, and effects can be changed for a particular waveform audio file. 
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Using the Media Control Interface (MCI) 


The Media Control Interface, or MCI, is the application interface to multime¬ 
dia device control using MMPM/2. This interface provides a device-indepen¬ 
dent way of manipulating multimedia devices, either alone or in groups. This 
interface allows applications to open device contexts or instances of media 
devices and control them. Some media devices, such as Compact Discs and 
Laserdiscs, are simple devices. Other media devices, such as waveform audio 
and MIDI, are compound devices because they require a file on which to oper¬ 
ate. The MCI interface is a message passing interface. Each MCI call requires 
a command, a set of flags, and a command-specific data structure. Along with 
the information passed on in the MCI application programming interface or 
API, information is sent back to the application in the form of multimedia 
extended PM messages. All APIs describe in this section are 32-bit interfaces. 


MCI APIs 


The two main APIs are: mciSendString and mciSendCommand. These 
APIs allow applications to open, manipulate, and close multimedia devices. 
These two APIs provide the same level of function, but they export different 
interfaces. The mciSendString API exports a English like string interface. 
The mciSendCommand API exports a more traditional procedural interface; 
message, flags, and data structure. 

The first main MCI API is mciSendCommand . This API sends a command 
or message with a set of flags and a data structure to a Media Control Device. 
This API is referred to as the procedural API, because it provides a traditional 
PM programming interface to the media devices. The syntax of the 

mciSendCommand API is: 


31 
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ULONG mciSendCommand (USHORT 

usDevicelD, 

USHORT 

usMessage, 

ULONG 

ulParaml, 

PVOID 

pParam2, 

USHORT 

usUserParm) 


where the parameters are as follows: 

• usDevicelD: The device ID number returned on the MCI_OPEN mes¬ 
sage. This parameter is ignored on the MCI_OPEN message, and the ID 
is returned in the MCI_OPEN_PARMS structure. 

• usMessage: The command or message to execute. All commands start 
with the prefix MCI_. 

• ulParaml: A ULONG flag variable that is associated with the command 
or value in usMessage. 

• pParam2: A pointer to a data structure that is associated with the com¬ 
mand or value in usMessage. 

• usUserParm: An application-defined USHORT that is returned on 
MM_MCINOTIFY message. Note: This will become clearer when we talk 
about asynchronous notifications. 

This API requires the application to know the exact flag values and data 
structures for the particular media device. Although there are a set of common 
MCI flags and a default data structure per message, Media Control Devices 
may define additional flags and replacements MCI data structures for individ¬ 
ual MCI commands. One important point is to initialize or memset these data 
structure to Os so that erroneous data is not sent in the data structure. 
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Figure 3-1. mciSendCommand Structure 

This is why the second MCI API, mciSendString , is the recommended API 
for multimedia device independent applications. In other words, if your appli¬ 
cation is not designed to work with only one particular media device, it should 
use the mciSendString API for media control commands. Note: MCI has a set 
of system commands, some of which have no string equivalent. The syntax of 
the mciSendString API is: 


ULONG mciSendString (PSZ 

pszCommand, 

PSZ 

pszReturnString, 

USHORT 

usReturnLength, 

HWND 

hwndCal1 back, 

USHORT 

usUserParm) 


where the parameters are as follows. 

• pszCommand: MCI command string of the general form <command> 
<device name> <arguments>. 
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• pszReturnString: An application-supplied buffer for return data. This 
field can be NULL if no return data is requested. 

• usReturnLength: Length of pszReturnString buffer. 

• hwndCallback: A PM window handle to be used on MMPM/2 asynchro¬ 
nous notifications. 

• usUserParm: This is an application-defined USHORT that is returned 
on MM_MCINOTIFY message. Note: This will become clearer when we 
talk about asynchronous notifications. 

MMPM/2, specifically the Media Device Manager or MDM, will take the 
pszCommand parameter and parse the command string into three parts. The 
first part is the command or message. Remember that the mciSendCommand 
has the message or command number as one of it’s parameters. The second 
part to be parsed is the device name to which this command is to be sent. This 
is determined one of three ways; device element, device name, or alias, all of 
which will be explained later in the section on device names and aliases. The 
final part to be parsed is the command arguments. The command arguments or 
keywords describe actions for the command or message. From the command 
arguments a set of MCI flags and a data structure can be built. Given this set 
of parsed information, along with the usUserParm and hwndCallback parame¬ 
ters, a mciSendCommand equivalent call is constructed by the MDM. 

The MDM uses Media Control Device or MCD supplied “command tables” 
and a default “command table” to parse string commands into their correct 
mciSendCommand forms. This function of command string parsing is transpar¬ 
ent to MMPM/2 applications. Command tables are arranged into blocks of com¬ 
mands with a set of valid keywords for each message. These tables are loaded 
into memory and parsed very efficiently, so there is very little performance 
impact. One tip for using the string interface is to use lower case strings. This 
will help speed up the processing of the string commands with respect to the 
command tables. 
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mciSendCommand () mciSendString () 



Figure 3-2. MDM String Parser 

The following samples illustrate that MMPM/2 applications are unaware of 
the actual device they are talking to. One final note on these two APIs: 
MMPM/2 applications can mix mciSendCommand and mciSendString calls 
to the same device ID. The sample below shows a MCI_PLAY command being 
sent to a Compact Digital (CD) device using both the mciSendCommand and 
mciSendString APIs. 


//define INCL_MCI0S2 
//include <os2me.h> 


USHORT usUserParm; 

/* 

user defined parameter 


*/ 

USHORT usCDDevicelD; 

/* 

device ID return on the open command 

*/ 

HWND hwndWindow; 

/* 

window handle 


*/ 

MCI_PLAY_PARMSP1 ayParms 

/* 

MCI_PLAY_PARMS structure 


*/ 

ULONG rc; 

/* 

return code 


*/ 

PIayParms.hwndCal1 back = hwndWindow; 

PIayParms.ulFrom = OL; /* media locations to start 

playing from 

*/ 

piayParms.ulTo = 10000L; 

/* 

media location to play to 


*/ 

UserParm++; 

/* 

may want to keep track of 

this command 

*/ 


re = mciSendCommandCusCDDevicelD, 

MCI_PLAY, 

MCI_NOTIFY | MCI_FR0M | MCI_PLAY, 

(PV0ID)&P1ayParms, 
uslIserParm); 


Figure 3-3. mciSendCommand PLAY command sample 










36 Developing Multimedia Applications Under OS/2 


#define INCL_MCI0S2 
^include <os2me.h> 


USHORT usCDDevicelD; 

/* 

device ID return on the open 

command */ 

HWND hwndWindow; 

/* 

window handle 

*/ 

USHORT usUserParm; 

/* 

user defined parameter 

*/ 

CHAR szReturnString[128]; 

/* 

return buffer 

*/ 

CHAR szCommand[128]; 

/* 

command string buffer 

*/ 


ULONG re; 

strepy((PSZ)szCommand, 1 pi ay cdl from 0 to 10000 notify!); 
usllserParm++; /* may want to keep track of this command*/ 

rc = mciSendString ((PSZ)szCommand, 

NULL, /* no return data requested*/ 

0L, 

hwndWindow, 
usUserParm); 


Figure 3-4. mciSendString PLAY command sample 

Both code samples accomplish the same function, but the mciSendString 
sample has a number of advantages. First, it is device-independent from the 
application’s view. Second, from a user’s view, it is more natural to deal with a 
string command. The commands, device names/aliases, and arguments can be 
surfaced to the end user. There is even a PM applet, MCISTRNG that comes 
with the MMPM/2 Toolkit, that allows typing in string commands to be sent to 
MMPM/2. Most of the samples in the book will be written using the 
mciSendString interface, except for certain system level commands where 
there is no string equivalent. 


HIGH LEVEL APIs 

Along with the two MCI APIs discussed above, three additional APIs are avail¬ 
able to perform playback and recording of audio and playback of video. These 
APIs can be used to provide general playback and recording within a single 
API. Some applications for example may just want to play an audio clip, such 
as help message or an error message. The APIs accomplish this for the applica¬ 
tion without opening, playing, and closing a audio device. The three 
APIs are: 

• mciPlayFile 

• mciPlayResource 

• mciRecordAudioFile 
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The first API, mciPlayFile , provides a simplified method to play a multime¬ 
dia data file, or an audio element of a Resource Interchange File Format or 
RIFF file. This API can be executed in either a synchronous or asynchronous 
mode, depending upon the flags supplied with this function. A display window 
handle can be provided for video playback. The default audio or video device is 
used for playback. 

The second API, mciPlayResource , is similar to the mciPlayFile API 
except that the element to be played is a program resource not a file. The name 
of the data file to play is retrieve from the program resource. This data file is 
then opened using the Multimedia Input/Output or MMIO subsystem, and the 
ID is passed on to the MCI interface. When the playback is complete data file 
is closed, the resType parameter defines the type of data file to playback. The 
current set of resource types are: 

• RT_WAVE: Digital audio. 

• RT_AVI: Digital video. 

• RT_RMID: MIDI. 

• RT_RIFF: RIFF (any of the above types can be contained within this 
resource type). 

The final API, mciRecordAudioFile , provides a simplified method of 
recording an audio file or MMIO compound audio file element. This function 
provides a simplified audio recorder window. The recording continues until the 
recorder window is closed. The only data type recorded is 11 kHz, mono, Pulse 
Code Modulated (PCM), audio data. This audio data type is supported by most, 
if not all, audio adapters. These audio files can then be used by the 
mciPlayFile API, or by the other MCI commands requiring audio files. 


REXX PROGRAMMING INTERFACES 


In addition to MMPM/2 programming interfaces, a set of REXX functions are 
available for multimedia. These functions provide a subset of MMPM/2 string 
interface functionality. Because the command interface requires command 
data structures as one parameter, it is not supported from REXX. The 
MMPM/2 REXX functions are: 

• mciRxSendString 

• mciRxGetErrorString 

• mciRxGetDevicelD 



38 Developing Multimedia Applications Under OS/2 

• mciRxInit 

• mciRxExit 

These functions allow REXX command files to execute most string functions. 
There are a set of limitations that should be noted here. These limitations have 
to deal with resource management of MMPM/2 devices and PM notifications. 
REXX command files cannot receive PM messages; therefore they can not 
receive MMPM/2 notification messages. This means that REXX command files 
should adhere to the following rules: 

• Commands should be issued with the wait string keyword. 

• Devices should be opened shareable and then acquire exclusive 
instance. 

• Commands requiring a PM session cannot be executed under REXX (use 
PMREXX). 

The mciRxSendString , mciRxGetErrorString, and mciRxGetDevicelD 
functions provide access to the mciSendString, mciGetErrorString, and 
mciGetDevicelD APIs respectively. These functions have parameters that are 
almost identical to those of their MCI APIs counterparts. Aside from the limi¬ 
tations noted above, these interfaces provide identical functions to their MCI 
counterpart interfaces. The following sample gives a MMPM/2 enabled REXX 
command file. 


/* 

** Initialize REXX for MMPM/2 functions 
*/ 

rc = RXFUNCADD(‘mciRxInit’, ‘MCIAPI’, ‘mciRxINIT’) 
rc = mciRxlnit() 

/* 

** Open the wave device with the audio file. If an error is returned then ge 
the error string. 

*/ 


MCICommand = ‘open bell.wav alias wavealias wait shareable’ 
rc = mciRxSendString(MCICommand, ‘ReturnString’, ‘O’, ‘0’) 
if rc <> 0 then 
do 

Errorrc = rc 

rc = mciRxGetErrorString(Errorrc , ‘ErrorString ’) 
end 
el se 
do 


Figure 3-5. REXX Command File Sample 
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MCICommand = ‘acquire wavealias exclusive instance wait’ 
rc = mciRxSendString(MCICommand, ‘ReturnString’, ‘O’, ‘0’) 
if rc <> 0 then 
do 

Errorrc = rc 

rc = mciRxGetErrorString(Errorrc , ‘ErrorString’) 
end 
el se 


/* 

** PI ay the wave file. 
*/ 


do 

MCICommand = ‘play wavealias wait’ 

rc = mciRxSendStringCMCICommand, ‘ReturnString*, ‘O’, ‘0’) 
if rc <> 0 then 
do 

Emorrc = rc 

rc = mciRxGetErrorString(Errorrc , ‘ErrorString’) 
end 
el se 

/* 

** Close the wave audio device. 

*/ 


do 

MCICommand = ‘close wavealias wait’ 

rc = mciRxSendString(MCICommand, ‘ReturnString’, ‘O’, ‘0’) 
end 
end 

rc = mciRxExit() 


Figure 3-5. REXX Command File Sample (Continued) 

The previous sample shows how to open, acquire, play, and close a 
waveaudio device and file. A very similar structure is used for recording, 
except that the record command should be issued without the notify keyword. 
A stop command would have to be issued some time later to stop the recording. 

Notice in the sample that mciRxInit and mciRxExit are used to set up and 
tear down the communication with the mciRxSendSting , 
mciRxGetErrorString and mciRxGetDevicelD functions. Also notice that 
the mciRxGetDevicelD function is not included in the sample. This is because 
without mciSendCommand support, knowing the device ID is not very 
important. As the limitations state, digital video play back and record is not 
supported from REXX, because a PM window handle is required. To playback 
and record digital video, the REXX command file must be run using PM REXX. 
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DEVICE NAMES AND ALIASES 


From the string interface, media devices can be opened using one of three 
methods for the “device name.” The first is the actual system-defined name. 
MMPM/2 has a set of logical device type names such as “cdaudio” and “digi- 
talvideo.” A device ordinal is appended to the end of these logical device types 
depending on the multimedia hardware installed in the users system. The ordi¬ 
nal number is simply an index number used mainly with multiple devices of 
the same type. For example, if a user had two CD ROM drives installed in his 
or her system, then that user would have logical devices cdaudioOl and 
cdaudio02. 

The Media Device Manager also maintains a default logical device for each 
device type in the system. For example the default CD audio logical device is 
cdaudioOl. This default can be changed using the setup applet supplied with 
MMPM/2. So, for opening a device using the logical device type name, the 
application could specify either the full logical name such as cdaudioOl or the 
default logical name cdaudio. Most systems will have only one device of a par¬ 
ticular type, so the default type name will suffice. 


“open digital video alias mymovie wait” 
or 

“open digitalvideo02 alias mymovie wait 


The second method for opening a device, for devices that use files, is to sub¬ 
stitute the file name for the device name. The Media Device Manager main¬ 
tains a list of both file extensions and OS/2 Extended Attributes (EA) that are 
to be associated with a particular media device. For example, digitalvideoOl 
will have the file extension “AVI” associated with it. So to open a device using 
the file name applications should use a command string like the following: 


“open macaw.avi alias mymovie wait” 


The Media Device Manager will determine that the file extension “AVI” is 
associated with digitalvideoOl and open that media device. A unique file exten¬ 
sion and EA can be associated with only one logical device name at any given 
time. These associations are set installation time, but they can be changed 
using the setup applet or using the MCI_SYSINFO message. 

The final method of opening media devices is to use a system alias. System 
aliases are defined at install time, but they can be changed using the MMPM/2 
setup applet. These aliases are considered static aliases since they are valid 
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until changed, even after re-boots of the system. The alias “Compact Disc” is 
the system defined alias for the CD device at install time. 


“open ‘DigitalVideo Player’ alias mymovie wait shareable” 


As you can see from this example, the system alias is a multiple word “key¬ 
word”. We are using a multiple word keyword for the device name and there¬ 
fore it must be enclosed in quotes. 

These three methods allow applications to open devices through the string 
interface. The first and third methods can also be used to reference media 
devices once they are opened. In addition, dynamic aliases are also supported. 
Dynamic aliases provide for a reference to a media device instance after it is 
opened. First of all, if an application opened a device using the default device 
type name for a media device, it could also use the default name on subsequent 
commands. For example: 


“open cdaudio notify shareable” 

“play cdaudio from 0 to 10000 notify” 


This method of referring to a media device using the default name or logical 
device name works fine if an application is only going to use one “instance” of a 
device per OS/2 process. If an application could have multiple device 
“instances” open per OS/2 process, that application should use dynamic aliases 
to refer to the different device instances. For example, an application wants to 
open two waveform audio devices, one for background music and the other for 
voiceover. The application should do the following: 


“open musicl.wav alias music wait shareable” 
“open voicel.wav alias voice wait shareable” 


The application would then refer to the different device instances using the 
dynamic alias names. These alias names are dynamic for two reasons. First, 
when that device instance is closed, the aliases is deleted. Second, the alias is 
known only within the OS/2 process that opened the media device. Therefore, 
different OS/2 processes can use the same dynamic alias names. We talk more 
about device instances when we get to MMPM/2 resource management. 
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OPEN COMMAND 


The open command creates and initializes a media device instance for a par¬ 
ticular media device. A media device instance is a logical instantiation of a 
media device. A device ID or handle is returned on the open command and 
should be used on all future commands for that media device instance. Certain 
system commands do not require a device ID. From the string interface, an 
alias is used instead of a device ID. The association of the alias and device 
instance ID is maintained by the MDM. The alias for the device instance is set 
on the open command. The keyword alias is used on the open command to 
associate an alias name with a given media device instance. For example: 


“open cdaudio alias cdl wait shareable 


will open an instance of the CD audio device in shareable mode and associate 
the name cdl to the media device instance. Other commands for that device 
instance would use cdl as the second parameter of their string. For example: 


“play cdl notify” 


would play the CD audio instance associated with the name cdl. Aliases can 
only be used from the string interface. Device IDs are required when using the 
procedural interface or mciSendCommand API. 

It might be required for certain applications to mix their use of 
mciSendString and mciSendCommand. This is because not all commands 
are available from the string interface. To mix the use of these two APIs, the 
device ID must be available from the string interface. The device ID is 
returned, by MDM, in the pszReturnString parameter of the mciSendString 
API. The device ID is returned as a null terminated string representation of 
the ID. Applications should use the “C” function atol (ASCII to Long) to con¬ 
vert the string representation of the ID to the numeric representation of the 
ID. The ID can then be used by the mciSendCommand API. 

Two other keywords are available for the open command: shareable and 
type. As you might have guessed, shareable opens the media device instance 
in a fully shareable mode. This should be the mode every device instance is 
opened in, except when exclusive mode is absolutely required. Without the 
shareable keyword, the device instance is opened in exclusive mode. These 
modes are described in more detail in the section on resource management. 
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The other keyword for the open command is type. The type keyword lets 
an application override MMPM/2 on determining which device the open com¬ 
mand is intended for. For example the command: 


“open music.wav alias mymusic shareable type waveaudio02 wait 


would try and open the device that had the extension wav associated with it, 
but the type keyword overrides that and tells MMPM/2 to open the waveau- 
dio02 device. This keyword is useful multiple devices in the system could han¬ 
dle a given file (extension or EA), but more control on picking that device is 
required. 

One flag not available from the string interface for the open command is 
MCI_OPEN_MMIO. This flag allows applications to utilize MMIO to access 
data files and then pass in the MMIO handle or HMMIO. The HMMIO is 
passed in the pszElementName field of the open data structure. MMPM/2 will 
then use this handle to access the data file for processing. 


COMMAND EXECUTION MODE 


Almost all MCI commands can be executed in one of three modes; synchronous, 
asynchronous with notification, or asynchronous without notification. The 
default method is asynchronous without notification. This means that if nei¬ 
ther wait or notify keyword is specified on a command then the command is 
started and control is returned to the application as soon as some amount of 
error processing is done. The amount of error checking that is performed before 
control is returned depends on the Media Control Device type. The application 
is not notified on completion of the command regardless, of whether or not the 
command was executed successfully. This default command execution mode is 
not recommended. 

The recommended mode for command execution is either synchronous or 
asynchronous with notification upon completion of the command or error. To 
have a command execute in synchronous mode, applications use the wait key¬ 
word on the command. Commands that are going to take a short amount of 
time to execute or commands that are returning information should be execut¬ 
ed in synchronous mode. A short amount is probably on the order of a 1/4 of a 
second. Commands like capability, status, info, and set either return infor¬ 
mation or execute quickly. 

The final mode of execution for MCI commands is asynchronous with notifi¬ 
cation. The keyword notify is used to specify that the command is to execute 
asynchronous and send back a MM_MCINOTIFY message upon successful 
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completion of the command or if an error occurs during execution. This does 
not mean that the application making the call with the notify keyword or flag 
will not get an error on the call. The Media Device Manager (MDM) and the 
Media Control Devices (MCD) processing the given command are going to per¬ 
form a certain level of error processing before returning to the application. If 
an error is encountered during this error processing, then the error is returned 
to the application and the command is not completed. This error processing 
mainly has to do with the checking of parameters and values. This form of 
command execution should be used for any type of command that may take an 
extended period of time to execute. Some commands fitting in this description 
are: play, record, seek, pause, stop, paste, cut, copy, rewind, resume, 
load, and cue. The application will receive a MM_MCINOTIFY message to 
the PM window handle specified on the call. This window handle is specified in 
the hwndCallback parameter of the mciSendString API or the 
hwndCallback field of any MCI parameter structure passed on the 
mciSendCommand API. The notification message is posted to the window 
handle via the PM WinPostMSG API. The parameters MP1 and MP2 
returned with the MM_MCINOTIFY message are defined as: 

• MP1 

> usNotifycode (USHORT): Specifies whether the command executed 
successfully or not. The possible values are: 

MCI_NOTIFY_SUCCESSFUL: The command executed 
successfully. 

MCI_NOTIFY_SUPERSEDED: Another command (same type) 
with the notify flag was received before this command completed. 

MCI_NOTIFY_ABORTED: This command was interrupted by 
another command and was unable to complete execution. 

Any other value indicates an error occurred during command exe¬ 
cution. The mciGetErrorString API can be used to get the error 
string associated with the given error number. 

> usUserParameter (USHORT): This is the user parameter passed in 

on all mciSendCommand and mciSendCommand calls. 

• MP2 

> usDevicelD (USHORT): The ID number of the Media Device 
Instance. 

> usMessage (USHORT): The MCI command or message this notifica¬ 
tion is for. There may be more than one outstanding command for any 
given media device instance. 
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Applications should be multi-threaded to be able to handle these asynchro¬ 
nous notifications without “hanging” the system. If the application does not 
continue to process its message queue then the system may seem unresponsive 
to other desktop events (such as focus changes). Given the unknown and often 
long time multimedia commands can be executing (playing, seeking, etc.), mul¬ 
tiple threads and asynchronous commands are required to maintain system 
and desktop responsiveness. The following code example shows how a 
Presentation Manager should handle MM_MCINOTIFY messages: 


case MM_MCINOTIFY: 


usNotifyCode = (USHORT) 

SH0RT1FR0MMP( 

mpl); 

/* 

/* 

Notification 
Type 

Code 

*/ 

*/ 

usUserParm 

= (USHORT) 

SH0RT2FR0MMP( 

mpl); 

/* 

User Parameter 

*/ 

usDevicelD 

= (USHORT) 

SH0RT1FR0MMP( 

mp2); 

/* 

Media Device 

ID 

*/ 

usMessage 

= (USHORT) 

SH0RT2FR0MMP( 

mp2); 

/* 

MCI message 


*/ 


switch (usCommandMessage) 
{ 

case MCI_PLAY: 


switch (usNotifyCode) 
{ 


case MCI_NOTIFY_SUCCESSFUL: 

/* 

The command completed 

*/ 


/* 

successfully. 

*/ 

break; 

case MCI_N0TIFY_SUPERSEDED: 

/* 

The command was superseded 

*/ 


/* 

by another PLAY command 

*/ 

break; 

case MCI_N0TIFY_AB0RTED: 

/* 

The PLAY command was 

*/ 


/* 

aborted by another command 

*/ 

break; 

default: 

/* 

The PLAY command did not 

*/ 


/* 

complete successfully. 

*/ 


rc = mciGetErrorString((ULONG)usNotifyCode, 
pszErrorBuffer, 

(USHORT)128); 

break; 

} /* end switch */ 
break; /* MM_MCINOTIFY case */ 


Figure 3-6. Notification Code Sample 
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This code sample shows how a MMPM/2 application might be set up to han¬ 
dle notification messages for a play command. The notify codes MCI_NOTI- 
FY_SUPERSEDED and MCI_NOTIFY_ABORTED can only occur if the 
application issued another MCI message for the same media device instance 
during the execution of a MCI message. The MCI_NOTIFY_SUPERSEDED 
can only occur if the same command is issued. The MCI_NOTIFY_ABORTED 
can occur if any other command is issued that stops the processing of the 
current MCI message. If the play command is processing, and a seek, stop, or 
record is issued then the abort will be sent back to the application. 

RESOURCE MANAGEMENT 
Shareable State 

MMPM/2 provides a system wide resource management policy for the multime¬ 
dia devices known to it. This resource management policy attempts to fully uti¬ 
lize the resources of the multimedia devices. For example, if a audio card can 
playback two mono waveform files concurrently, then MMPM/2 will allow this 
to happen. Device sharing is at the heart of MMPM/2’s resource management. 
Media device instances can be in one of three sharing states: fully shareable, 
media device instance exclusive, and media device exclusive. These sharing 
states are granted and assigned on a media device state. That is to say, when a 
media device instance is created, a sharing state is assigned (based on the 
exclusive or shareable flag) on the open command. The sharing state of a 
media device instance can be changed using the acquire and release com¬ 
mands. Before we discuss these two commands, let’s talk about the three shar¬ 
ing states. 



Most Restrictive 


Least Restrictive 


Figure 3-7. Sharing Modes 
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The first and most preferred state is fully shareable. This state means that 
at any point in time the media device instance can be made inactive to allow 
some other media device instance (for the same media device) to become active. 
To make a media device instance fully shareable, on the open command spec¬ 
ify the shareable flag. You might be wondering why you would want my 
media device instance to become inactive and how would you know when it 
became inactive. To answer the first part, OS/2 is a multi-tasking operating 
system with the end user controlling what is running in the foreground and 
background. By having fully shareable media device instances, the end user 
can manage his or her system to his or her needs. Because a media device 
instance is shareable, it will only be made inactive when another media device 
instance is requesting to be made active (open or acquire command). We 
answer the second part of the question later in this chapter. 

The second sharing state is media device exclusive instance. This state 
means that this media device instance is not to be made inactive for any rea¬ 
son. This state should be used whenever an application can not handle the 
media device instance being made inactive; for example during a record or a 
group of related set commands. 

The final sharing state is exclusive. Exclusive is different from exclusive 
instance because not only is the given media device instance not allowed to be 
made inactive, but the entire media device is held exclusively by that media 
device instance. Only that media device instance will be allowed to be active 
for that media device. The exclusive state can be a waste of system multimedia 
resources. This sharing state should be avoided because exclusive instance 
state provides all the protection an application needs from having its media 
device instance being made inactive. Unfortunately this is the default state on 
the open command (shareable or exclusive instance not specified). 

MM_MCIPASSDEVICE Message 

An MMPM/2 message is sent to applications to let the application know when 
a media device instance is going to be made active or inactive. The message is 

MM_MCIPASSDEVICE. 

• MP1 

> usDevicelD (USHORT): The ID number of the Media Device 
Instance. 

> usReserved (USHORT): Unused. 

• MP2 

> usEvent (USHORT): An event indicating whether the media device 
instance is being made active or inactive. (MCI_GAINING_USE or 
MCI_LOSING_USE) 
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> usReserved (USHORT): Unused. 

Applications will receive this message from MMPM/2 via WinPostMsg calls 
to the window handle passed in on the open command. Even on the open com¬ 
mand, until a MM_MCIPAS8DEVICE message (MCI_GAINING_USE) is 
received, the media device instance is inactive and cannot receive most MCI 
commands except close, status, info, and capability. The following code 
sample shows how to set up a case statement in the MainDialogProc proce¬ 
dure to handle the MM_MCIPASSDEVICE message. 


case MM_MCIPASSDEV ICE: 


usDevicelD = (USHORT) SH0RT1FR0MMP( mpl); 

/* 

Media Device 

ID */ 

if (SH0RT1FROMMP(mp2) == MCI GAINING USE) 

{ 

/* 

GAINING USE 

*/ 

} 

el se 

/* 

LOSING USE 

*/ 


break; 


Figure 3-8 . MM_MCIPASSDEVICE Code Sample 

Applications can modify the sharing state of a media device instance as well 
as make an inactive media device instance active and vice versa. The system 
commands acquire and release allow applications to do this. The acquire 
command allows an application to request a given device instance be made 
active or change the sharing state to that of exclusive or exclusive instance. 
Three keywords are available for the acquire command: exclusive, exclu¬ 
sive instance and queue. The first two keywords change the sharing state of 
the device instance. The third keyword allows the acquire command to be 
queued up for execution as soon as the resource required is available. This is 
useful when another device instance has the same device in some kind of exclu¬ 
sive mode. 

Let’s go through the process of acquiring a media device instance. The first 
step is to decide whether we require the given device instance in an exclusive 
mode or not. The second step is to decide whether we can wait for an extended 
amount of time for the acquire command to execute. 

The acquire command will attempt to make the given media device instance 
active and change the sharing state for the device instance if the exclusive or 
exclusive instance keywords are specified. If the given device instance is 
already active, then only the sharing state of the device instance is modified, if 
the exclusive or exclusive instance keyword is specified. As the sharing 
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mode diagram shows, exclusive mode is the highest or most expensive mode 
when it comes to resource management. The acquire command with the 
exclusive or exclusive instance flag can be used to toggle between the two 
exclusive modes when needed. 

The queue keyword does not change the operation of the acquire command, 
but it does queue the request up if it can not be met right away. Commands 
such as close and release may allow queued acquire commands to now exe¬ 
cute. Acquire commands that are queued, are put in a FIFO queue main¬ 
tained by the MDM. If the media device instance is closed, and it has a queue 
acquire command outstanding, it is removed from the queue. 

The release command performs the inverse of the acquire command. It 
changes the sharing state of the given device instance to be fully shareable. It 
can also allow other inactive device instances to gain use of that device 
resource. This is accomplished using the return resource keyword. If this 
keyword is not specified on the release command, then only the sharing state 
for the given device instance is changed. Applications should use the return 
resource keyword when they no longer require the given device instance to be 
active. Using this keyword does not mean that the device instance will be made 
inactive. It simply means that other inactive device instances for that device 
will be made active. 


CAPABILITY COMMAND 


The capability command allows MMPM/2 applications to query the current 
capabilities of a media device instance. There are a set of required capabilities 
to which every media device must respond. There are additional capabilities to 
which only specific devices and device types respond. Let’s discuss the required 
set of capabilities first. The following list gives the required set of capabilities 
to which every MMPM/2 media device must answer. 

• has audio: The media device instance will return TRUE if the device 
supports audio playback. 

• has video: The media device instance will return TRUE if the device 
supports video playback. 

• can play: The media device instance will return TRUE if the device can 
play. 

• can eject: The media device instance will return TRUE if the device can 
eject the media (i.e., Compact Disc device). 

• can save: The media device instance will return TRUE if the device can 
save data after a recording. 
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• compound device: The media device instance will return TRUE if the 
device requires a file. 

• uses files: The media device instance will return TRUE if the device 
requires a file. 

• can setvolume: The media device instance will return TRUE if the 
device supports software control of the volume level. 

• can lockeject: The media device instance will return TRUE if the 
device can disable the manual ejection of the device media. 

• can record: The media device instance will return TRUE if the device 
supports recording 

• device type: The media device instance will return its device type 
string. The following device types can be returned currently: ampmix, 
cdaudio, cdxa, digitalvideo, sequencer, waveaudio, videodisc, 
overlay, other. 

• message command: The media device instance will return TRUE if the 
device supports the command. 

Applications should use these basic or required capabilities to deter¬ 
mine the characteristics of the media device instance. This helps 
MMPM/2 applications remain device-independent by knowing what 
functions are basic and whether the media device supports them. For 
example, the application can use the following command to determine 
if it should allow the end user to control the volume of the device 
instance. (Remember that not all CD drives have software volume 
control.) 


capability cdl can setvolume wait 


The wait flag should always be used with the capability command when 
using the string interface because this command returns information. Only on 
a wait can the return information be converted to its string representation by 
the Media Device Manger. 


STATUS 


The status command allows applications to query various runtime states of a 
media device instance. Items such as; volume, position, length, and time 
format are basic to all media devices. Status commands can be issued to an 
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inactive device instance. Since status commands return information, they 
should be issued with the wait keyword. If the notify keyword is used, no 
return information can be given to the application. If an application wants to 
issue the STATUS command with the MCI_NOTIFY flag, then the status 
data structure must remain valid until the MM_MCINOTIFY message is 
received. 

Although the status command is used to determine the current state of a 
device instance, it is not required to determine certain aspects of the device 
instance. Information such as the mode (playing, seeking, etc.), time format, 
and others can be maintained by the application itself. The application can 
keep a variable as to the currently set time format or device state. This can 
help avoid unnecessary MCI calls. 


EDITING COMMANDS 


MMPM/2 provides a set of MCI messages to be used for audio and video edit¬ 
ing. These messages are: 

• MCI_COPY 

• MCI_CUT 

• MCI.DELETE 

• MCI__PASTE 

• MCI_REDO 

• MCIJJNDO 

Editing operations can be performed using both Presentation Manager clip¬ 
board and application-supplied buffers. The MCI_UNDO and MCI_REDO 
commands undo or redo the previous copy, cut, delete, or paste operation. 
MMPM/2 supports the following list of clipboard and resource types: 
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Type 

Description 

CF_RMID and RT_RMID 

RIFF data that has a RMID chunk or regular MIDI 
with an “MT” header. 

CF_RIFF and RT_RIFF 

RIFF data, including all of the headers. 

CF_WAVE and RT_WAVE 

RIFF data that has a WAVE chunk. 

CF_AVT and RT_AVI 

RIFF AVI data. An entire video file is placed in the 
clipboard. 


Table 3-1. Clipboard and Resource Format Types 


These types are defined in the 0S2MEDEF.H header file. 

The copy, cut, delete, and paste commands all work with the 
MCI_EDIT_PARMS data structure. 


typedef struct _MCI_EDIT_PARMS { 
HWND hwndCal1 back; 

ULONG ulStructLen; 

ULONG ulFrom; 

ULONG ulTo; 

PVOID pBuff; 

ULONG ulBufLen; 

PVOID pHeader; 

} MCI_EDIT_PA RMS; 


This structure contains the from and to fields required for these four com¬ 
mands. In addition, it contains a pointer to an application defined buffer to be 
used on the cut, copy and paste commands when the MCI_TO_BUFFER or 
MCI_FROM_BUFFER flags are specified. 


Copy 


The copy command copies the given range of data from the media device ele¬ 
ment to the clipboard or the application buffer. The position of media remains 
the same after the command completes. The MCI_TO_BUFFER and 
MCI_FROM_BUFFER flags are used to specify where the data is to be copied 
to/from. If the MCI_FROM_BUFFER flag is used then the data is copied from 
the application-supplied buffer. If it is not specified then the data is copied 
from the media element. If the MCI_TO_BUFFER flag is specified then the 
data from the media file is copied into the application-supplied buffer. If this 
flag is not specified then the data is placed in the clipboard. 
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Cut 

The cut command removes a specified range of data from the media device ele¬ 
ment and puts it into the application-supplied buffer or the clipboard. The posi¬ 
tion after the cut command is the from position if the from keyword is speci¬ 
fied. If it is not specified, then the current position remains as is. If from key¬ 
word is not specified, then the cut starts at the current position. If the to key¬ 
word is not specified then the cut is to the end of the media device element. 
This command also supports the MCI_TO_BUFFER flag. If it is specified, 
then the data is placed into the application-supplied buffer. If it is not, then the 
data is placed in the PM clipboard. 

Paste 

The paste command issues a delete on the selected range (if the difference 
between the from and to is more than 0) and inserts the data from the clip¬ 
board or buffer into the file at the from position. The position of the media after 
this command is at the end of what was pasted. The convert keyword is sup¬ 
port by this command. The convert keyword converts the data into the format 
of the media device element. The conversions possible are waveform audio 
(Pulse Code Modulation or PCM) only. 


Settings 

Conversions 

Channels 

Mono to Stereo, Stereo to Mono 

Sampling Rate 

11025, 22050 or 44100 

Data Type 

16-bit to 8-bit or 8-bit to 16-bit 


Delete 


The delete command removes the specified range of data from the media 
device element. The position of the element after the operation is the from 
position if specified, or the previous position if it is not specified. 
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SYSTEM COMMAND 

Sysinfo 


There are two forms of the sysinfo command. The first form is the standard 
sysinfo command used to query basic information about the media devices 
currently installed in the system or currently open. These basic system infor¬ 
mation commands are support by the string interface. There are two basic 
types of system information that an application can retrieve. The first is infor¬ 
mation about the number of media devices installed in the system or the num¬ 
ber of media devices open. This information can be for a particular media 
device type or for all media devices. For example, if an application wanted to 
know the number of media devices installed in the system it would use the fol¬ 
lowing string. 


“sysinfo all quantity wait” 


To find the number of CD audio media devices in the system, the application 
would use the following string: 


“sysinfo cdaudio quantity wait 


By adding the keyword open to either of these strings an application could 
find out the number of open media device instances. Open does not distinguish 
between active or inactive device instances. 

The second type of basic system information is the system defined name for 
a particular device number or ordinal. The keyword to use is name number 
where number is the ordinal number. This form of the sysinfo command pro¬ 
vides no useful information and should not be used. 

The second form of sysinfo command is not available from the string inter¬ 
face. This is the extended form of the sysinfo command. It allows application 
(mainly install or setup) to add, delete, and modify information about media 
devices and MMPM/2 system settings. To understand this set of system infor¬ 
mation, a little background information is required. 

Media device information is stored in a file called “mmpm2.ini.” This file 
currently contains four types of blocks of information. 

1. System Values 

2. Drivers 

3. Media Device Information 

4. Device Type Default Devices 
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[systemvalues] 
cl osedcaption=0 
mastervolume=77 
headphones=l 
speakers=l 
workpath=D:\MM0S2 
qosvalue=65537 
qoserrorflag=2 
[ibmdigvidpiayerOl] 

VERSIONNUMBE R=1 

PRODUCTINF0=IBM Digital Video Player 

MCDDRIVER=SVMC 

MCDTABLE=MDM 

RESOURCENAME=VIDEO PLAYER 
DEVICEFLAG=1 
DEVICETYP E=12 
SHARETYPE=3 
RESOURCEUNITS=10 
RES0URCECLASSES=2,10,1 
EATYPES=Di gi tal Video 
ALIASNAM E=Digital Video Player 
EXTNAMES=1,AVI 
C0NNECT0RS=1,3,,1 
[drivers] 

Digitalvideo=IBMDIGVIDPLAYER01 
Waveaudio=IBMWAVEPAS1601 
Sequencer=IBMSEQPAS1601 
Ampmix=IBMAMPMIXPAS1601 
CDaudio=IBMCD020_l 

C D X A=IB M C D 0 X A_1 

Speaker=SPEAKER 
Headphone=HEADPHONE 
Microphone=MICROPHONE 
[ibmwavepasl601] 

VERSIONNUMBE R=1 

PR0DUCTINF0=Pro AudioSpectrum 16 
MCDDRIVER=AUDIOMCD 
VSDDRIVE R=A U D101F 
PDDNAME=PAS161$ 

MCDTABLE=MDM 

RESOURCENAME=ProAudioSpecWl 

D EVIC E F LAG=1 

DEVICETYP F=7 

SHARETYPE=3 

RESOURCEUNIT S=1 

RES0URCECLASSES=1,1 

C0NNECT0RS=1,3,1BMAMPMIX PAS1601,1 

PARMSTRING=F0RMAT=1,SAMPRATE=22050,B P S=16,C HAN N F LS=1,DIRECTI0N=PLAY 


Figure 3-9. MMPM2.INI File Sample 
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ALIASNAME=Digital Audio 
EXTNAMES=2,WAV,VOC 
[ibmseqpasl601] 

VERSIONNUMBE R=1 

PR0DUCTINF0=Pro AudioSpectrum 16 
MCDDRIVE R=MIDIM C D 
VSDDRIVE R=A U D101F 
PDDNAME=PAS161$ 

MCDTABLE=MDM 

RESOURCENAME=ProAudioSpecSl 

D EVIC E F LAG=1 

DEVICETYP E=8 

SHARETYPE=3 

RESOURCEUNIT S=1 

RESOURCEC LAS S ES=1,1 

C0NNECT0RS=1,1,1BMAMPM IXPAS1601,1 

PARMSTRING=MIDITYPE=Pro AudioSpectrum 16 CHANNELS=1111111111111111 
ALIASNAM E=MIDI 
EXTNAMES=1,MID 
[ibmampmixpasl601] 

VERSIONNUMBE R=1 

PR0DUCTINF0=Pro AudioSpectrum 16 
MCDDRIVER=AMPMXMCD 
VSDDRIVE R=A U D101F 
PDDNAME=PAS161$ 

MCDTABLE=MDM 

RESOURCENAME=ProAudioSpecAl 

DEVICEFLAG=2 

DEVICETYP E=9 

SHARETYPE=3 

RESOURCEUNIT S=2 

RES0URCECLASSES=2,1,1 

VALIDCOMBINAT10 N S=1,2,2,1 

C0NNECT0RS=5,4,,0,9,,0,8,,0,10,,0,7,,0 

PARMSTRING=TREBLE=50,BASS=50,PITC H=5 0,GAIN=70,BALANCE=50,V 0 L=100,1N P U T= LIN E,0 U 
TPUT=SPEAKER,RES0URCEDLL=AUDI0IF,RCID=5 
[ibmcd020_ll 
VERSIONNUMBE R=1 
PR0DUCTINF0=T0SHI BA 
MCDDRIVER=CDAUDI0 
VSDDRIVER=GENCDVSD 
PDDNAME=CDR0M 
MCDTABLE=MDM 
RESOURCENAME=F: 

D EVIC E F LAG=1 
DEVICETYP E=3 
SHARETYPE=2 
RESOURCEUNITS=1 
RES0URCECLASSES=1,1 


Figure 3-9. MMPM2.INI File Sample (Continued) 
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PARMSTRING=Drive=F,Model=TOSHIBA CD-ROM XM-3401TA 
C0NNECT0RS=2,6,HEADPHONE,1,2,,0 
ALIASNAME=Compact Disc 
[ibmcd0xa_l] 

VERSIONNUMBE R=1 
PRODUCTINF0=T0SHI BA 
MCDDRIVER=IBMCDXA 
VSDDRIVER=GENCDVSD 
PDDNAME=CDROM 
MCDTABLE=MDM 
RESOURCENAME=F: 

DEVICE FLAG=1 
DEVICETYP E=17 
SHARETY P E=2 
RESOURCEUNIT S=1 
RES0URCECLASSES=1,1 

PARMSTRING=Drive=F,Model=TOSHIBA CD-ROM XM-3401TA 
C0NNECT0RS«1,5,,0 
ALIASNAME=CD-ROM XA 
EXTNAMES=1,XA 
[speaker] 

VERSIONNUMBE R=1 
PRODUCTINFO=SPEAKER 
RESOURCENAME=SPEAKER 
DEVICEFLAG=2 
DEVICETYP E=13 
SHARETY P E=1 
RESOURCEUNITS=0 
RES0URCECLASSES=1,1 
C0NNECT0RS=1,15,,0 
[headphone] 

VERSIONNUMBE R=1 
PRODUCTIN F0=H EADPHONE 
RESOURCENAM E=H EADPHONE 
D EVIC E F LAG=2 
DEVICETYP E=14 
SHARETY P E=1 
RESOURCEUNIT S=0 
RESOURCECLASSES=l,1 
C0NNECT0RS=1,15,,0 
[microphone] 

VERSIONNUMBE R=1 
PRODUCTINF0=MICROPHONE 
RESOURCENAME=MICROPHONE 
DEVICEFLAG=2 
DEVICETYP E=15 
SHARETYPE=1 
RESOURCEUNITS=0 
RESOURCECLASSES=l,1 
C0NNECT0RS=1,16,,0 


Figure 3-9. MMPM2.INI File Sample (Continued) 
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The system value block contain master audio settings and quality of services 
(QOS) settings. We discuss this later when we talk about the masteraudio 
command. The second block is the drivers block. This contains the names of all 
the media device blocks. The names are unique and are supplied when the 
media device is installed in the system. The media device names are organized 
according to media device type. The third block(s) are the media device blocks. 
These blocks contain all the information required by the MMPM/2 system to 
access that media device. Although the MMPM2.INI file is ASCII based, it is 
not meant to be updated by anything else besides the sysinfo commands. 

The extended sysinfo commands allow that information to be added, modi¬ 
fied, or deleted. The setup applet also allows users to change some of that 
information such as file extension and EA associations. The final block (which 
may or may not be present) assigns a media device as the default device for 
that device type. These extended sysinfo commands deal with the following: 

• General Media device information 

• Media device specific parameters 

• Media device aliases 

• Media device file extension and EA associations 

• Media device default connections 

Applications in general will not use the extended commands. They are 
documented in the MMPM/2 Programming Reference and the MMPM/2 
Subsystem Development Guide. These commands are used mainly by MMPM/2 
installation programs. 

Masteraudio 

The masteraudio command allows applications to change the master volume 
setting and to query the master volume, headphone, and speaker settings. 
From the string interface, the keywords are volume, headphones, and 
speakers. These master or global settings are queried by the various Media 
Control Devices. The media devices use these master settings to determine 
their true volume settings (master * device instance setting), as well as using 
the speaker and headphone settings to determine whether output to a device 
instance speaker or headphone is allowed. This allows the user to control sys¬ 
tem settings much like he or she can on a home stereo system. Although the 
string interface supports only the querying of the headphone and speaker set¬ 
tings, the procedural interface allows all settings to be queried and set. The 
masteraudio settings may be enhanced by IBM at some point, to add additional 
system-wide audio settings. 
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These master audio settings are used by the Media Control Devices in two 
ways. The first way is when a media device instance is opened that media 
device issues a master audio command to determine the current headphone 
and speaker settings as well as the current master volume setting. The master 
volume setting is then used to set the current device volume setting. The 
device volume is a multiplication of the master volume setting and the device 
setting. For example, if the master volume setting is 75%, and the device vol¬ 
ume setting is 75%, then the actual device volume is about 42% (75% * 75%). 
The state of the headphones/speakers determines whether a device that pro¬ 
duces audio will enable or disable these “jacks.” For example, if the master 
speaker setting is disabled then the audio will play, but not a sound will be 
heard. 

The second way the master audio settings are used is while a device 
instance is active. If a master audio setting is changed, then the Media Device 
Manager will send commands to all of the active device instances notifying 
them. These active device instances will then adjust the device instance’s audio 
settings based on the master audio settings. This is how master volume 
changes are reflected by each device instance. 

Connection 

The connection command is used to query information about media device 
connections. Media device connections allow one media device to be connected 
logically to another media device. For example, when a waveaudio device is 
opened, an ampmix device instance is opened by the waveaudio device and con¬ 
nected to the waveaudio device instance. The waveaudio device instance con¬ 
trols the data movement of the audio data, and the ampmix device instance 
controls the physical audio device. Another example of this is a “streaming” cd 
audio device. The connection command allows applications to query the con- 
nected-to devices and to assign aliases to them. Using the device alias or device 
ID for the connected to device, the application can send commands to that con¬ 
nected device instance. This is an important feature when there are commands 
that the application wants to send to the connected to device. For example com¬ 
mands that deal with bass, treble, gain, and other audio effects. To find the 
connected to ampmix device instance, an application would issue the following 
strings. 


“open bong.wav alias myaudio wait shareable” 

“connection myaudio query type wave stream alias myampmix wait 
“set myampmix bass 75 wait” 

“set myampmix treble 90 wait” 
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As more advanced audio and video amp/mixer functions become available 
the ability to perform these functions will become more valuable. 

Connectorinfo 

The connectorinfo command returns information about the connectors on a 
media device. This allows applications to determine the types and number of 
connections a media device has. It also can be used to determine if a particular 
connection is possible or valid. 

The following is a list of connector types supported by each MMPM/2 device: 
Amplifier Mixer Device 

• MCI_AMP_STREAM_CONNECTOR 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_MICROPHONE_CONNECTOR 

• MCI_LINE_IN_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 
CD Audio Device 

• MCI_CD_STREAM_CONNECTOR 

• MCI_HEADPHONES_CONNECTOR 
Sequencer Device 

• MCI_MIDI_STREAM_CONNECTOR 
Waveform Audio Device 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 
Videodisc Device 

• MCI_LINE_OUT_CONNECTOR 

• MCI VIDEO OUT CONNECTOR 
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Digital Video Device 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_MICROPHONE_CONNECTOR 

• MCI_LINE_IN_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 

• MCI_VIDEO_IN_CONNECTOR 

• MCI_VIDEO_OUT_CONNECTOR 

Defaultconnection 

The defaultconnection command is used to make, break, and query the 
default connections for media devices. Some media devices do not support con¬ 
nector and therefore do not support connections. A good use of the defaultcon¬ 
nection command is to change where the output of an audio stream goes. For 
example, if waveaudioOl had a default connection to ampmixOl and to the user 
or application, the audio output of the speakers attached to ampmix02 could be 
changed using the defaultconnection. 


“defaultconnection waveaudioOl break type wave stream to ampmixOl totype amp 
stream wait” 

“defaultconnection waveaudioOl make type wave stream to ampmix02 totype amp 
stream wait” 


Group 


The group command, as its name implies, allows multiple device instance to 
be logically grouped together. The device instances can be grouped in one of 
two ways: piecemeal and nopiecemeal. Piecemeal is the default, and it means 
that the state of the individual device instances are independent. Some can be 
active and some can be inactive. The second group mode is nopiecemeal. This 
means that all the device instances in the group are in the same device state. If 
one or more or the device instances becomes active or inactive, then all of the 
device instances become active or inactive. The nopiecemeal mode of a group 
is the most valuable aspect of a group for applications. Very often applications 
need more than one media device instance to do their job. The nopiecemeal 
mode guarantees that all the resources required for the entire group are either 
available or not available. 
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Groups have an ID and can be given an alias, just like individual media 
device instances. MCI commands can be issued to a group and MMPM/2 will 
send the same command to all the individual device instances of the group. 
The list of possible commands that can be issued to a group are: 

• acquire 

• release 

• play 

• record 

• seek 

• close 

• stop 

• pause 

• resume 

MCI notification messages are still sent from the individual device 
instances. If one or more members of a group are closed, then the group is 
deleted and the ID and the alias for that group are no longer valid. For exam¬ 
ple if an application wanted to acquire exclusively all the resources for a group 
it could do the following: 


“open cdaudio alias cdl shareable wait” 

“open music.wav alias myaudio shareable wait” 

“group mygroup make nopiecemeal (cdl myaudio) wait” 
“acquire mygroup exclusive instance wait” 


After the acquire command the application has all the resources locked in 
exclusive instance mode, the now command can be issued to the group or to the 
individual devices instances of the group. Applications should not issue com¬ 
mands to a group that requires return information, such as status, 
capability, or info. Care should be used when issuing commands like play 
and record to a group when not all media device instances are playing or 
recording. 
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ERRORS 


Errors from both the mciSendString and mciSendCommand APIs are 
returned as ULONGs. The low order word of the error contains the error num¬ 
ber and the high order word contains the device ID. The entire error ULONG is 
used by MMPM/2 during processing of the mciGetErrorString API. 
Applications should do a test on only the low order word of the return code to 
determine if an error occurred. If an error is detected the mciGetErrorString 
API can be used to convert the numeric error code into its string representa¬ 
tion. The syntax of the mciGetErrorString API is: 


ULONG mciGetErrorString (ULONG ulError, 

PSZ pszBuffer, 
USHORT usLength) 


where the parameters are as follows. 

• ulError: The error code returned by mciSendString or 
mciSendCommand. 

> pszBuffer: Pointer to application buffer to hold the error string. 

> usLength: Length of application-supplied buffer ( pszBuffer ). 

If the error MCIERR_OUTOFRANGE is return from a call to 
mciGetErrorString, then the given error has no string equivalent. The buffer 
passed in should be large enough to hold the error string. A size of 128 to 256 
bytes should be sufficient to hold most, if not all, error strings. If the buffer 
passed in to mciGetErrorString is smaller than the error string, then the 
buffer will be filled with just what it can hold based on the field usLength. For 
a description of the MMPM/2 error codes, see Appendix E. There are certain 
error codes that were not mapped to new MMPM/2 error codes. If you are 
unable to find the error code in Appendix E check the list of current OS/2 error 
codes. 


SYSTEM VALUES 


In addition to MCI device and MMPM/2 system commands, there are a set of 
system values. These system values are initialized when MMPM/2 is installed 
and can be modified by the mciSetSysValue API or using the Setup applica¬ 
tion. The current list of system values are: 
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System Value 

Type 

Description 

Master volume 

ULONG 

Master volume level. 

Headphones 

ULONG 

Headphones enabled(TRUE/FALSE) 

Speakers 

ULONG 

Speakers enabled(TRUE/FALSE) 

Workpath 

PSZ 

MMPM/2 temporary file workpath. This is 
a fully qualified drive:path. 

Quality of Services(QOS) 

ULONG 

System wide quality of service value. 

QOS error 

ULONG 

Description of error occurring during QOS 
reservation. 


Table 3-2. System Values 

Since these system values have a unique index number, MMPM/2 may 
extend this set in the future to cover additional system level settings. Since 
these values are system defined, they should only be modified by the MMPM/2 
supplied setup application. 

System Value Querying 

To query system values, use the mciQuerySysValue API. The iSysValue 
parameter is the system defined number for the particular system value. Each 
system value has an associated programming type. The system value table 
defines the types for the current set of system values. The type is important 
when making a mciQuerySysValue or mciSetSysValue call. Both calls have 
a PVOID to represent the value type. The true value type is used by MMPM/2 
to store and retrieve the system value. 

Synchronization 

MMPM/2 provides internal synchronization for movie files by utilizing the syn¬ 
chronization capabilities of the Sync/Stream Manager. On the other hand 
applications require timing events during playback and recording. These tim¬ 
ing events are used for two purposes. The first is for continuous timing events 
based on the current playback or recording time. This type of continuous notifi¬ 
cation could be used to update internal counters or external user interfaces to 
reflect the current location of the playback or recording. This continuous notifi¬ 
cation is provided using the setpositionadvise command. The setposition- 
advise command allows applications to set one periodic notification message. 
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The notification message that is returned to the application is the 

POSITIONCHANGE message. 


“open cdaudio alias cdl shareable wait” 

“set cdl time format milliseconds wait” 

“setpositionadvise cdl on every 250 return 250 wait” 
“play cdl notify” 


To set up periodic notification messages, an application issues the setposi- 
tionadvise command with time interval set. The following example shows 
how to request a MM_MCIPOSITIONCHANGE message every 1/4 second or 
250 milliseconds during playback. 

Notice in the example that the interval set is based on the current time for¬ 
mat the device instance is using. The example set the time format to millisec¬ 
onds before issuing the setpositionadvise command. Only one position advise 
command can be active at a time per device instance. If you want to change the 
time interval, you must “turn off’ the current time interval and set a new one. 
The following example shows how to change the time interval from 250 mil¬ 
liseconds to 500 milliseconds. 


“setpositionadvise cdl off every 250 return 250 wait 
“setpositionadvise cdl on every 500 return 500 wait” 
“play cdl notify ” 


The application will receive the MM_MCIPOSITIONCHANGE message at 
a regular interval as determined by the interval defined on the setpositionad¬ 
vise message. The MsgParaml parameter contains the user parameter and 
device ID. The user parameter is in the high order word of MsgParaml. This 
user parameter is the value that is passed using the return keyword on the 
setpositionadvise message. 

The MsgParam2 parameter of the MM_MCIPOSITIONCHANGE message 
contains the time that this message was generated. This value is returned in 
MMTIME units regardless of time format when the setpositionadvise mes¬ 
sage was issued. MMTIME units are 1/3000 of a second. The reason that this 
time unit is always returned is twofold. The first reason is that the time format 
of the media device instance may have changed from the time the setposition¬ 
advise message was issued till the MM_MCIPOSITIONCHANGE message 
is received by the application. There is no parameter left on the MMJMCIPO- 
SITIONCHANGE message to specify the time format the time value is being 
returned. The second reason is that MMTIME units are supported by all 
MMPM/2 devices. 
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case MM_MClPOSITIONCHANGE: 

usUserParm = (USHORT) SH0RT1FR0MMP( mpl); /* User ParameterD */ 

usDevicelD = (USHORT) SH0RT2FR0MMP( mpl); /* Media Device ID */ 

ulMMTime = (ULONG)(mp2); /* Position time in */ 

/* MMTIME units. */ 

/* update linear slider based on the ulMMTime value. */ 


break; 


The second type of notification message is the MM_MCICUEPOINT mes¬ 
sage. This message is return to the application when a particular time or cue- 
point is reached during playback or recording. To set a cuepoint, issue the 
setcuepoint message. The following example shows how to define a cuepoint 
at 10.5 seconds into playback. 


“open cdaudio alias cdl shareable wait” 

“set cdl time format milliseconds wait” 
“setcuepoint cdl on at 10500 return 10500 wait” 
“play cdl notify” 


When 10.5 seconds is reached during the playback, the MM_MCICUE- 
POINT message is sent to the application based on the window handle sup¬ 
plied with the cuepoint message. 

Cuepoint messages are very similar to positionadvise message with regard 
to setting and removing. They differ in that an application can have multiple 
cuepoints outstanding, based on the capabilities of the device. These cuepoint 
provide one-time notification of a particular time during playback or recording. 
Cuepoints are persistent, they remain in effect for the media device instance 
even after they are encountered. The only time cuepoints are removed is by 
using the setcuepoint message to remove them or by loading a new file ele¬ 
ment. In fact cuepoints can not be set for a compound device if a file is not 
loaded. 

MM_MCICUEPOINT messages, like positionadvises, are generated only 
while the media device instance is playing or recording. During all other opera¬ 
tions, including seek, no cuepoint recognition takes place. 



Memory Playlist 


Using the Media Control Interface (MCI) 67 


Besides being able to play files, MMPM/2 provides for audio playback using 
application-supplied buffers. The memory playlist is a data structure con¬ 
taining programming like instructions. These instructions include control and 
data instructions. The data instructions contain pointers to application buffers 
to play from or record to. The playlist record structure is a set of 4 ULONGs. 
The first ULONG is the instruction and the next three ULONGs are the 
operands for that instruction. 


Instruction 

Operand 1 

Operand 2 

Operand 3 

ULONG 

ULONG 

ULONG 

ULONG 


Figure 3-10. Playlist Record Format 


The playlist instructions are fixed length (4 ULONGs) and are numbered 
starting with number 0. Each playlist instruction can be identified by using its 
absolute instruction number. Control instructions like BRANCH, CALL, and 
LOOP have an absolute instruction number as one of their operands. 

The following table shows the available playlist instructions. Each instruc¬ 
tion is given with a description of the instruction and a description of each of 
its three operands. 


Instruction 

Description 

BRANCH.OPERATION 

Transfer control to another instruction in the playlist 
structure. 

Operand 1 - Ignored. 

Operand 2 - The absolute instruction number to 
branch to. 

Operand 3 - Ignored. 

CALL.OPERATION 

Transfer control to the absolute instruction number 
specified in Operand 2. The instruction number imme¬ 
diately following this instruction is saved for use on 
the RETURN instruction. 

Operand 1 - Ignored. 

Operand 2 - Absolute instruction number control is 
transferred to 

Operand 3 - Ignored. 


Table 3-3. Playlist Instructions. 
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Instruction 

Description 

CUEPOINT.OPERATION 

This instruction places a data record into the data 
stream. This data record is relative to the DATA 
instruction that follows it. This instruction is ignored 
during recording. 

Operand 1 - Application defined parameter to be 
returned as the low USHORT of MsgParaml in the 
MM_MCICUEPOINT message. 

Operand 2 - Offset in MMTIME units for the actual 
time the MM_MCICUEPOINT message should be 
generated. 

Operand 3 - Ignored. 

DATA_OPERATXON 

This instruction specifies an application-supplied data 
buffer to be play from or recorded to. 

Operand 1 - Pointer to application buffer. 

Operand 2 - Length of application buffer. 

Operand 3 -Current position in application buffer. 

This operand is updated by the system during play¬ 
back or recording. For playback, it is the number of 
bytes that have been sent to the output device 
handler. For recording, it is the number of bytes that 
have been placed in the application buffer. 

EXITOPERATION 

This instruction denotes the end of the playlist. 

Operand 1 - Ignored. 

Operand 2 - Ignored. 

Operand 3 - Ignored. 

LOOP.OPERATION 

This instruction provides for iteration within the 
playlist. The current iteration (Operand 3) must be ini¬ 
tialized by the application 

Operand 1 - Number of times the loop is to be 
executed. 

Operand 2 - Target absolute instruction number to 
branch to when the loop condition fails. 

Operand 3 - Current iteration. 


Table 3-3. Playlist Instructions. (Continued) 
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Instruction 

Description 

MESSAGE_OPERATION 

This instruction causes a MM_MCIPLAYLISTMES- 
SAGE message to be returned to the application. 

Operand 1 - Ignored. 

Operand 2 - ULONG that is returned in MsgParam2 
of the MM_MCIPLAYLISTMESSAGE message. 

Operand 3 - Ignored. 

NOP.OPERATION 

This is a no-op instruction. 

Operand 1 - Ignored 

Operand 2 - Ignored. 

Operand 3 - Ignored. 

RETURN_OPERATION 

This instruction causes control to be returned to the 
playlist instruction number following the most recent¬ 
ly executed CALL instruction. 

Operand 1 - Ignored. 

Operand 2 - Ignored. 

Operand 3 - Ignored. 


Table 3-3. Playlist Instructions. (Continued) 


To use the memory playlist for audio playback or recording, applications 
must specify the MCI_OPEN_PLAYLIST flag on the open command. The 
pszElementName field should contain the pointer to the memory playlist struc¬ 
ture. Since the pszElementName field must contain a pointer, applications 
must use the mciSendCommand API for the open command in this case. The 
string interface can still be used for the other commands as long as an alias 
was set on the open command. 

Although the playlist structure can be updated dynamically, great care must 
be used when updating the playlist structure while it is in use. The 
MESSAGE and CUEPOINT instructions cause the message to be sent back to 
the application. These messages are not necessarily sent back in absolute real¬ 
time. If the application is depending on these messages to determine when to 
update the playlist structure, the playlist processor could actually be further in 
the structure than the application thinks. Applications should make use of 
multiple data buffers separated by MESSAGE and CUEPOINT instructions 
to determine when to update the playlist structure (change the contents or 
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pointer to data buffer). The MESSAGE instruction should be used more as an 
indicator as to when to refill a data buffer. The CUEPOINT instruction should 
be used to determine when data is consumed. The MM_MCICUEPOINT mes¬ 
sage will be returned to the application as soon as possible after the cuepoint 
data record is encountered. 

The control instructions provide the basic programming-like functions. 
The BRANCH instruction allows control to transfer to another absolute 
playlist instruction. Branching out of a subroutine, although not prohibited, is 
not recommended because an unused return address will remain on the 
playlist processor stack. Remember that the playlist instructions start from 0, 
not from 1. 

The LOOP instruction provides a basic loop until count is equal or greater 
than a maximum loop counter. The last playlist instruction in the loop is a 
BRANCH back to the LOOP instruction. The processing of the LOOP instruc¬ 
tion is as follows. If the current iteration (Operand 3) is less than the maxi¬ 
mum loop count (Operand 1), then the next playlist instruction is given control 
and the current iteration count is incremented. Otherwise the current iteration 
count is reset to zero, and control is transferred to the absolute instruction con¬ 
tained in Operand 2. It is up to the application to initially set the current itera¬ 
tion count (Operand 3) to zero. Otherwise whatever value is in Operand 3 will 
be used as the current iteration count. 
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Multimedia fundamentally consists of many different types of data. To deal 
with these various forms of data, MMPM/2 uses the Multimedia I/O subsystem 
or MMIO for short. The MMIO subsystem provides the means for an applica¬ 
tion to manipulate data, store data, and retrieve data from storage devices. 
These can be primary (for example, memory) or secondary (for example, CD- 
ROM, hard drive, diskette) storage devices. This storage access also includes 
local and remote (for example, network) access to data. The subsystem pro¬ 
vides ways to translate data between different types of formats. The MMIO 
interface includes a consistent set of interfaces that are common across file for¬ 
mats, storage systems, compression types. An important aspect of MMIO is the 
extendibility of the subsystem. A programmer with the MMPM/2 toolkit can 
add new file formats to the system easily. In addition, a developer can add sup¬ 
port for new compression and decompression routines (CODECs), as well as, 
new storage system types. 

To an application writer, MMIO provides the format independent interface 
for getting data to and from MMPM/2 from a storage device. Multimedia con¬ 
tent comes on a variety of media and formats. Each computer platform seems 
to have its own preferred data formats. Luckily, most hardware media for 
these different platforms is becoming standardized. Diskette drives are 720KB, 
1.44MB and 2.88MB in size. The CD-ROM standard is becoming the preferred 
media for distribution of software tools, games, and multimedia content. For 
the most part, the operating system provides the file system interfaces that 
hide the particulars of the actual storage media. The data, however, can be 
stored in many different formats with many different compression techniques. 
This is where MMIO helps application writers. The MMIO interfaces are an 
important aspect of MMPM/2. An application writer may choose to use the 
interfaces directly or not, however, MMPM/2 uses these interfaces internally. 
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The media control drivers and stream handlers use MMIO, so an application is 
usually using MMIO indirectly. 

This chapter will cover the essentials that a multimedia application will 
need to know to deal with a variety of audio, image, and movie (audio and 
video data) files using MMPM/2. In general, the information in this chapter 
will apply to all version of MMPM/2 up to and including multimedia in OS/2 
Warp. MMPM/2 version 1.1 was shipped as part of OS/2 2.1 and OS/2 for 
Windows. This chapter will also cover the functionality of the Video IN prod¬ 
uct, which provides video capture capability to MMPM/2. Video In is provided 
in the OS/2 Warp bonus pack. 

There are three sections in this chapter. The first section will introduce the 
architecture and some important general concepts of the MMIO subsystem. 
The second section of this chapter will discuss I/O procedures. It will provide 
the details of file format and storage system I/O procedures. It will also explain 
how an application can use the MMIO interfaces to access many types of data 
without understanding how the data is formatted within a given file format. 
This section has several programming samples to show how applications can 
use these MMIO services effectively. The third section of this chapter will dis¬ 
cuss CODEC procedures and how MMPM/2 uses them. It will also explain how 
an application can use CODEC procedures to compress and decompress data. 
Several programming samples show how applications can utilize CODEC pro¬ 
cedure interfaces. 


MMIO SUBSYSTEM ARCHITECTURE 

The MMIO subsystem consists of a MMIO manager and a set of installable 
procedures. There are three basic types of MMIO procedures: file format I/O 
procedures, storage system I/O procedures, and CODEC procedures. The 
MMIO manager provides a set of input and output services for dealing with 
data. It manages the installable procedures and routes messages to the appro¬ 
priate procedures when an application requests an I/O service. The manager 
provides services to install and remove procedures, as well as, services to iden¬ 
tify procedures based on search criteria. I/O procedures are really OS/2 dynam¬ 
ic link libraries (DLL) that are loaded by the MMIO manager when needed. 
Multiple I/O procedures can exist within the same DLL, since each I/O proce¬ 
dure can be referenced through a different entry point in the DLL. 

A file format I/O procedure provides function for identifying and manipulat¬ 
ing data of a particular file format, for example, opening, reading, writing, and 
closing a file. A file format procedure is an I/O procedure that manipulates 
data at the element level, with each procedure handling a different element 
type such as audio, image, or MIDI. An element can be considered a data file, 
or section of a data file that contains data of a particular type. A file format I/O 
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procedure processes the data “within” the object (element) and does not rely on 
any other file format I/O procedures to process the data. However, a file format 
procedure will probably call a storage system I/O procedure to obtain data 
within a file containing multiple elements. A file format I/O procedure may 
also call one or more CODEC procedures to compress or decompress the data. 

A storage system procedure is an I/O procedure that “unwraps” a data object 
for a file format procedure to access. Storage system procedures are unaware of 
the format of the data object contained within the wrapper. A standard storage 
system I/O procedure is the DOS storage system procedure, which acts as an 
interface to the OS/2 operating system file system. This is typically the FAT or 
HPFS file system accessed through the OS/2 DosOpen, DosRead , DosWrite , 
and DosClose file services. 

A CODEC procedure is a compressor or decompressor of data and typically 
operates on a buffer of data. The term CODEC is actually an acronym for 
Compression and DECompression. A CODEC is an algorithm used to either 
compress data into a smaller space, or to decompress some compressed data 
back into the original or close approximation of the original data. MMPM/2 
currently supports image and digital video CODECs. MMPM/2 does provide a 
set of audio CODECs, but it does not yet provide a public interface to install 
new audio CODECs or interface to them directly. These are used within 
MMPM/2 for playing audio and movie files that contain compressed audio. 



Figure 4-1. MMIO Subsystem Architecture Diagram 
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The MMIO manager receives all API calls with the prefix mmio from an 
application. It either handles the functionality of the call internally or routes 
the call to a particular I/O or CODEC procedure for processing. In some cases, 
the MMIO manager determines which I/O procedure to call and in others, the 
application can indicate a specific I/O procedure to use. All MMIO APIs are 32- 
bit entry points except for two that are 16-bit entry points: 
mmioFindElement and mmioRemoveElement. These are 16-bit APIs pro¬ 
vided for 16-bit applications and are used with the 16-bit APIs provided by the 
Media Control Interface (MCI). 

The MMIO manager uses MMIOM_ messages (all predefined MMIO mes¬ 
sages have a prefix of MMIOM_) to communicate with I/O procedures. Each 
type of procedure must be able to process a predefined set of MMIOM_ mes¬ 
sages. MMIO provides the ability for each I/O procedure to define its own 
MMIOM_ messages. These are called user-defined messages and are provided 
for and defined by the I/O procedure provider, not by an application or end user 
of the I/O procedure. Applications can send MMIOM_ messages directly to an 
I/O procedure by using the mmioSendMessage API. 


The Syntax of mmioSendMessage API: 

LONG mmioSendMessage (HMMIO hmmio, USHORT usMsg, LONG Paraml, 
LONG Param2) 


Some messages do not have a corresponding API, so the only alternative is 
to use the mmioSendMessage API to send the message to an I/O procedure. 
This API has four parameters: a message number, an HMMIO representing 
the I/O procedure to call, and two optional parameters. HMMIO is an MMIO 
file handle, similar to an OS/2 file handle, which is used to refer to the file 
object and any information associated with it. The mmioOpen API is used to 
open a file object and it returns an HMMIO. The mmioSendMessage API can 
not be used to communicate with a CODEC procedure. It is only used to pass 
messages to file format and storage system I/O procedures. 

All messages passed on an mmioSendMessage go through the MMIO man¬ 
ager which translates the HMMIO into an MMIOINFO structure and passes 
this data structure instead of a HMMIO to the I/O procedure. When a file 
object is opened with the mmioOpen API, the MMIO manager allocates a 
MMIOINFO data structure. This data structure is used to keep any relevant 
information about an open file object and is passed to the I/O procedure on 
each message. 
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typedef struct _MM101N FO { 


ULONG 

ulFIags; 

FOURCC 

fccIOProc; 

PMMIOPROC 

plOProc; 

ULONG 

ulErrorRet; 

LONG 

cchBuffer; 

PCHAR 

pchBuffer; 

PCHAR 

pchNext; 

PCHAR 

pchEndRead; 

PCHAR 

pchEndWrite; 

LONG 

1BufOffset; 

LONG 

1DiskOffset; 

ULONG 

aulInfo[4]; 

LONG 

1 LogicalFi1ePos; 

ULONG 

ulT ranslate; 

FOURCC 

fccChi1dIOProc; 

PVOID 

pExtraInfoStruct; 

HMMIO 

hmmio; 


} MMIOINFO; 


/* mmioinfo */ 
/* Open flags */ 
/* FOURCC of the IOProc to use */ 
/* Entry Point to IOProc to use */ 
/* Extended Error return code */ 
/* Buf size (if used), Fsize if MEM */ 
/* Start of I/O buff */ 
/* Next char to RD/WR in buffer */ 
/* Last char in buf can be read +1 */ 
/* Last char in buf can be written+1 */ 
/* Offset in buffer to pchNext */ 
/* Disk offset in file */ 
/* IOProc specific fields */ 
/* Actual file position */ 
/* Translation field */ 
/* FOURCC of Child IOProc */ 
/* Pointer to related data */ 
/* Flandle to media element */ 


Some of the fields are manipulated directly by the I/O procedure for its own 
purposes (e.g., pointers to other data structures). Typically, the I/O procedure 
will use the pExtralnfoStruct field to point to an I/O procedure specific data 
structure for additional instance information for a file object. 

The mmioSendMessage API is also used to send user-defined messages to 
an I/O procedure. The mmioSendMessage API requires that all user-defined 
messages be defined at or above the MMIOM_USER definition found in the 
MMPM/2 toolkit MMIOOS2.H header file. 


#define MMIOM_USER OxOFOO 

//define MMIOM_USER_END OxOFFF 


Each type of I/O procedure has a set of messages that it must support. In 
addition, an I/O procedure can support a set of optional messages that add 
robustness to the functionality of the I/O procedure, but are not required for 
most purposes. For example, audio and movie I/O procedures use different 
messages to access the data in a file. Movie I/O procedures provide the 
MMIOM_MULTITRACKREAD message as an interface to read audio and 
video data from a movie file. (A movie contains both audio and video data.) 
This interface is used by the MMPM/2 applets, and other subsystems within 
MMPM/2 to read movie data. Applets are small applications. Movie I/O proce¬ 
dures, however, can support the mmioRead API and corresponding 
MMIOM_READ message to read data from the file, but it is not required sup¬ 
port for MMPM/2 to operate properly. 
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Figure 4-2. HO Procedure Messages 


Audio I/O procedures, on the other hand, do require the MMIOM_READ 
message and mmioRead API to be supported for MMPM/2. This allows the I/O 
procedure to process audio files and use the data in the system. This type of I/O 
procedure does not have a need to provide support for the MMIOM_MULTI- 
TRACKREAD message, since audio files do not typically have multiple tracks 
of data like a movie file (multi-track support will be discussed later in this 
chapter). 

An important concept for message handling in an I/O procedure is that if an 
I/O procedure cannot handle a message, it will pass the message to its child I/O 
procedure. Typically, the child I/O procedure for a file format I/O procedure is a 
storage system I/O procedure. This allows storage system-specific messages to 
be passed to the storage system I/O procedure without requiring each file for¬ 
mat I/O procedure to interpret or understand the message. Refer to the Quality 
of Service Network Storage System section of this chapter for an example of 
this technique. 
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As a rule, it is always a good idea to initialize all fields of MMIO data struc¬ 
tures that are not used on an API to NULL. This also applies to unused or 
reserved parameters and bit flags. This will help to avoid problems and 
decrease the debug time for new applications. Any uninitialized variables may 
cause problems, since MMIO or an I/O procedure may attempt to interpret the 
unused parameter indeterminately. 

It is possible for an application to call the entry point of an I/O procedure 
directly and bypass the MMIO manager. In this case, the first parameter is 
always an MMIOINFO structure ( pmmioinfo ) and the second is the message 
number ( usMsg ). The mmioGetData API can be used to retrieve the contents 
of the internal MMIOINFO structure from the MMIO manager to use when 
calling an I/O procedure directly. This copy of the internal MMIOINFO must 
be used for direct calls to work correctly. It is only necessary to make this call 
once to initialize the MMIOINFO data structure. The syntax for a direct I/O 
procedure call is as follows: 


typedef LONG (APIENTRY MMIOPROC) (PVOID pmmioinfo, 

USHORT usMsg, 
LONG lParaml, 
LONG 1Param2); 

typedef MMIOPROC *PMMI0PR0C; 


Querying Error Information 

Some MMIO API calls return error codes, while other MMIO API calls return 
MMIO_ERROR, MMIO_CF_FAILURE or 0 in the case of error. For exam¬ 
ple, a call to mmioOpen will return an HMMIO, MMIO file handle. An 
HMMIO is a positive number greater than 0, therefore, the only possible error 
return would be 0 or a negative number. Since MMIO_ERROR, 
MMIO_CF_FAILURE, and 0 are not very informative as to the error that 
occurred, an alternative is used to return additional error information. In the 
case of mmioOpen , the MMIOINFO data structure passed on the pmmioinfo 
parameter has an ulErrorRet field that will contain any error return codes 
available. 

In other cases, no MMIOINFO structure is passed on the API call, so the 
MMIO subsystem provides an API to query additional information about the 
last error that occurred. The mmioGetLastError API may return an addition¬ 
al error return code. The actual information for this API is retrieved from the 
MMIOINFO data structure that the MMIO manager passes to an I/O proce¬ 
dure on all MMIOM__ messages. It is the responsibility of the I/O procedure to 
fill in the ulErrorRet field of the MMIOINFO structure with this error infor¬ 
mation. The first parameter on the mmioGetLastError API can be either an 
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HMMIO or HMMCF, in the case of compound file operations. A HMMCF is a 
MMIO compound file handle. The following code sample shows one possible 
usage. It will use the mmioCFOpen and mmioCFGetlnfo compound file 
APIs. These APIs are discussed in the Compound Storage System section of 
this chapter. 


ULONG ulRc = 0; 

HMMCF hmmcf = 0; 

ULONG ulBytes = 0; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Query additional error information example\n\n”); 
/* Open a compound file */ 

hmmcf = mmioCFOpen(“e: Wmydi r\\book\\code\\cfWcf.bnd”, NULL, 

NULL, MMI0_WRITE); 

if (!hmmcf) { 

/* error */ 
goto end; 


/* This API call will fail because the file was opened in */ 

/* write mode, needs to be open in read mode */ 

ulRc = mmioCFGetInfo(hmmcf, (PMMCFINF0)&u1 Bytes, sizeof(ULONG)); 

if (I ul Rc) { 

/* Get the real error return code */ 
ulRc = mmioGetLastError(hmmcf); 

/* Handle the error */ 
switch (ulRc) { 

case MMIOERR_WRITE_ONLY_FILE: 

printf(“Error, Please re-open the file in read mode.Vn”); 
break; 

case MMIOERR_INVALID_PARAMETER: 

printf(“Error, Invalid parameter on mmioCFGetlnfo call.\n”); 
break; 
default: 

printf(“Error, %1d\n”,ulRc); 



end: 

if (hmmcf) 

ulRc = mmioCFClose(hmmcf,0); 

printf (“ END: Query additional error information example\n\n”); 


Figure 4-3. Querying Additional Error Information Sample 
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I/O PROCEDURES 


There are two types of I/O procedures: File format and Storage system. A file 
format I/O procedure provides function for identifying and manipulating data 
of a particular file format. A storage system procedure is an I/O procedure that 
“unwraps” a data object for a file format procedure to access. Both of these 
types of I/O procedures work together to provide typical data access. This sec¬ 
tion of the chapter describes both types of I/O procedures in greater detail. This 
chapter also discusses how to effectively use the services that these I/O proce¬ 
dures provide. 

I/O Procedure Type 

An I/O procedure is either a file format I/O procedure or a Storage system I/O 
procedure. Typically, when installing or querying the format of an I/O proce¬ 
dure, it is necessary to know the type of the I/O procedure. The following two 
defines are used to indicate the type of an I/O procedure. 


MMI0_I0PR0C_ST0RAGESYSTEM 
MM 10_10P ROC_FILEFORMAT 


For example, the MMINIFILEINFO and MMFORMATINFO data structures 
contain an ulIOProcType field that contains this type information. (These data 
structures are discussed later in the chapter.) 

Media Type 

I/O procedures are categorized by the type of data that they can process and 
this categorization is known as a media type. Each I/O procedure has a specific 
media type, and this value is associated with an I/O procedure when it is 
installed in the system. The following media types are defined for use with the 
MMIO subsystem: 


MM 10_M E DIATY P E_IMAG E 

MM 10_M EDIATY P E_AU D10 

MM 10_M E DIATY P E_MIDI 

MMIO_MEDIATYPE_COMPOUND 

MMIO_MEDIATYPE_OTHER 

MMIO_MEDIATYPE_UNKNOWN 

MM 10_M E DIATY P E_DIGITALVIDEO 

MM 10_M EDIATY P E_M0VIE 
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The media type of an I/O procedure can be queried by using the 
mmioGetFormats API. The mmioGetFormats API can also be used to query 
other information about I/O procedures installed in the MMIO initialization 
file (MMPMMMIO.INI). The I/O procedures that MMPM/2 provides are listed 
in the MMPMMMIO.INI file. The MMPMMMIO.INI file contains important 
information about each I/O procedure that can be used through MMPM/2. 
Typically, I/O procedures are added to this file before being used, although 
there are alternatives to permanently installing an I/O procedure into the INI 
file. These methods will be discussed later in this chapter. 

The mmioGetFormats API returns a MMFORMATINFO data structure 
that has a ulMediaType field that represents the media type for this I/O proce¬ 
dure. When an I/O procedure is installed into the INI file using the 
mmioIniFileHandler API, an application defined MMINIFILEINFO data 
structure is passed with a ulMediaType field for that I/O procedure. The MMP¬ 
MMMIO.INI actually contains a MMINIFILEINFO data structure for each 
installed I/O procedure. 


FOURCC 


Each I/O procedure is identified by a unique FOURCC or FOUR-Character 
Code. A FOURCC exists in two forms: a four character null-terminated string 
or a 32-bit quantity (ULONG) representing a sequence of one to four ASCII 
alphanumeric characters. A FOURCC is always padded to four characters 
with blank characters on the right. The ULONG form will present the charac¬ 
ters in reverse order from the characters of the string. This is due to the Intel 
byte swapping memory transfers. Each file format must be installed with a 
unique FOURCC value that is used as an ID. FOURCCs can be lowercase, 
uppercase, or mixed case. Uppercase FOURCCs are typically registered as 
unique ID codes with Microsoft Corporation. Lowercase codes are not regis¬ 
tered, and therefore they are not guaranteed to be unique across operating sys¬ 
tem platforms or within the same system that may have several multimedia 
applications installed and using MMIO I/O procedures. 

A macro and an API have been created that can be used to convert between 
a ULONG FOURCC and a null-terminated string FOURCC. The 
mmioFOURCC macro converts four individual characters to a ULONG four- 
character code. The mmioStringToFOURCC API converts a null-terminated 
string to a ULONG FOURCC. This API includes the ability to convert the 
character string to uppercase as it is converted. The MMIO_TOUPPER flag 
on the second parameter of this API is used to do this. The following list con¬ 
tains some of the pre-defined FOURCCs used in MMPM/2: 
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#def ine 

FOU RCC_RIFF 

mmioFOURCCC ‘R’, 

4 I\ 

4 F\ 

4 F’ ) 

#def ine 

FOURCC_MEM 

mmioFOURCCC ‘M\ 

4 E\ 

4 M\ 

4 4 ) 

#define 

F0URCC_D0S 

mmioFOURCCC ‘D’, 

4 0\ 

‘S’ , 

4 4 ) 

#define 

FOURCC_BND 

mmio FOU RCC( ‘B’, 

4 N\ 

4 D\ 

4 4 ) 


I/O Procedure Identification 

For an application to use the MMIO subsystem to access a file object, the file 
must be opened with the mmioOpen API. During the process of opening a file 
object, the MMIO manager must know which file format I/O procedure to use 
to access this object. Three methods to identify which I/O procedure to use for 
accessing a file object are: 

1. Use the mmioIdentifyFile API to automatically identify the I/O 
procedure. 

2. Use the mmioOpen API to automatically identify the I/O procedure. 
(This is the similar to method 1, except the file is opened if successful.) 

3. Use the mmioOpen API and specify a particular I/O procedure to use. 

These methods only work for I/O procedures that are installed in the MMP- 
MMMIO.INI file. Refer to the I/O Procedure Installation section of this chap¬ 
ter for details on how to install an I/O procedure. 

The MMIO manager provides services to identify which, if any of the 
installed I/O procedures can be used to access a particular file object. In the 
event that an application does not know the format of the data in a file object, 
the MMIO manager can perform a format identification process. In this 
process, each I/O procedure is polled to determine whether or not it under¬ 
stands the data format. If any I/O procedure identifies the data format, then it 
is chosen to be used to access the file object. To identify a file format, an I/O 
procedure will typically open the file and attempt to read any file headers and 
interpret them in its format. Since this process will cause each I/O procedure to 
be called once, identification will take longer for I/O procedures that exist 
lower in the list. The I/O procedure installed last, is the first I/O procedure in 
the list. 

Method 1 and 2 use this process to perform the identify. The default search 
will proceed through all I/O procedures. This is usually not desirable because 
there can be many I/O procedures. Therefore, an application can specify the 
media type of the I/O procedure to search for, and this will limit the search to 
only I/O procedures of that type. The aulInfo[3] field of the MMIOINFO 
passed on these APIs can be used to specify the media type. The automatic 
identification process is the default operation of the mmioOpen API. 
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In method 3, an application can specify the FOURCC of the I/O procedure 
to use for the file open. The fccIOProc field of the MMIOINFO structure 
passed on the mmioOpen API call must contain the FOURCC. A flag, 
MMIO.NOIDENTIFY, can be used to indicate to the MMIO manager that no 
automatic identification should be done. This should be set so that the MMIO 
manager will fail the open if the file format can not be processed by the I/O 
procedure. 

For performance reasons, it is better to attempt to open a file using method 
3, and skip the identification process. Even if the FOURCC specified is a best 
guess, only one I/O procedure will be called. If this fails, then an identify using 
method 2 with the media type specified should be used. This will give the best 
performance in cases where, most of the time, an application uses files of a spe¬ 
cific format and always uses files of the same media type. The following code 
sample shows method 3, and method 2 in case of failure. 


ULONG ill Rc = 0; 

HMMIO hmmio = 0; 

MMIOINFO mmioinfo; 

FOURCC fccIOProc; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Identify and Open a Movie File example\n\n”); 

/* Let’s assume we don’t know if this is a movie file */ 

/* but attempt to open the file as an AVI movie file */ 

fccIOProc = mmioFOURCCC‘A’,’V’,’I’,’ ‘); 

memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 
mmioinfo.fccIOProc = fccIOProc; 
hmmio = mmioOpen(“e: Wmmos2\\moviesWmacaw.avi ”, 
mmioinfo, 

MMI0_READ+MMI0_N0IDENTIFY); 

/* Possibly file was not identified */ 
if (!hmmio) { 

/* Attempt to open the file as a movie file */ 
memset(&mmioinfo, *\0’, sizeof(MMIOINFO)); 
mmioinfo.aulInfo[3] = MMI0_MEDIATYPE_M0VIE; 
hmmio = mmi oOpen (“e: Wmmos2\\movi esWmacaw. avi ”, 

&mmioinfo, MM 10_READ); 

Figure 4-4. I/O Procedure Identification Sample 
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/* Could not identify the file as a movie file, */ 
/* so I can’t process this type of file */ 

if (Ihmmio) { 

/* error */ 
goto end; 

} 


end: 

if (hmmio) 

ulRc = mmioClose(hmmi o,0); 

printf (“ END: Identify and Open a Movie File example\n\n”); 


Figure 4-4. HO Procedure Identification Sample (Continued) 

I/O Procedure Installation 

Before an I/O procedure can be used by the MMIO subsystem, it will need to be 
installed in the system. Since MMIO services are based on individual I/O pro¬ 
cedures being available as loadable DLLs, there exists a list of known and 
usable I/O procedure DLLs. All of the available I/O procedures are identified or 
listed in the MMPMMMIO.INI file. MMPM/2 does provide a set of pre-installed 
I/O procedures. Other products, such as IBM’s PerfectImage/2, install their 
own I/O procedures when they are installed into the system. Application writ¬ 
ers may also want to install additional I/O procedures as well. Therefore, 
MMIO provides several ways to install I/O procedures into the 
MMPMMMIO.INI file. (Note: This book does not discuss how to write an I/O 
procedure. Refer to the IBM MMPM/2 publications and toolkit for more infor¬ 
mation on writing I/O procedures.) There are basically three methods to install 
an I/O procedure: 

1. Use the mmioOpen API to temporarily install a particular I/O procedure 
and open a file. 

2. Use the mmioInstalllOProc API to semi-permanently install an I/O pro¬ 
cedure into the MMIO manager table of loaded I/O procedures. 

3. Use the mmioIniFileHandler API to permanently install an I/O proce¬ 
dure into the MMPMMMIO.INI file. This will make the I/O procedure 
available permanently. 

The I/O procedures provided by MMPM/2 are installed permanently when 
MMPM/2 is installed on your system. Only application provided I/O procedures 
would need to be installed using one of the previously mentioned methods. 
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In method 1, an application can temporarily install an I/O procedure when 
opening a file. If the I/O procedure is a dynamic link library (DLL) that has 
been loaded using the OS/2 DosLoadModule API. The application can per¬ 
form a DOSQueryProcAddr API call to retrieve the address of the entry point 
to the I/O procedure. The entry point address for the I/O procedure will be 
passed on the mmioOpen API to indicate to the MMIO manager that an I/O 
procedure is being temporarily installed. When an I/O procedure is installed in 
this manner, it is only available for use on this open file instance. It will not be 
added to the MMIO manager internal I/O procedure table, so it will not be 
available to other processes or mmioOpen requests. This method is useful to 
applications that want to replace a default I/O procedure on a temporary basis. 
For this method, all fields of the MMIOINFO passed on the mmioOpen call 
must be NULL except for the plOProc field that must contain the address of 
the I/O procedure entry point. The following code sample shows the temporary 
installation of a dummy I/O procedure that happens to be a routine within an 
application, not a separate DLL. Typically, an I/O procedure would be self-con¬ 
tained within a separate DLL. 


INT main( VOID ) 

{ 

ULONG ulRc = 0; 

HMMIO hmmio = 0; 

MMIOINFO mmioinfo; 

system(“cl s”) ; 
printf(“\n\n”); 

printf (“ START: Install and Open a Movie File Using Dummy I/O 

Procedure Sample\n\n”); 

/* Open a file and install the dummy I/O procedure as the */ 

/* I/O procedure to use to access this file. */ 

memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.plOProc = I0Proc_Entry; 

hmmio = mmio0pen(“e:\\mmos2WmoviesWmacaw.avi”, 

&mmioinfo, MMI0_READ); 

/* Check if error occurred */ 
if (!hmmio) { 

/* error */ 
goto end; 

} 


end: 

if (hmmio) 


Figure 4-5. Temporary I/O Procedure Installation Sample 
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ulRc = mmioClose(hmmio,0); 

printf (“ END: Install and Open a Movie File Using Dummy I/O Procedure 
Sample\n\n”); 

return ulRc; 

} /* End of main */ 


/•k-k-k-k'k'k-k'k-k'k'k-k-k-k'k'k-k-k-k-k-k-k'k-k'kJc'k-k-k-k'k'k'k'k-k/ 

/* Dummy I/O procedure entry point */ 

^'k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k'kic'k-k-k-k-k-k-k-k'k'k'k-k-k-k-k/ 

LONG API ENTRY I0Proc_Entry ( PVOID pmmioStr, 

WORD wMessage, 
LONG lParaml, 
LONG 1Param2 ) 


PMMI0INF0 pmmioinfo; 

/* Clear the error return before anything happens */ 
/* to ensure valid results. */ 

if (pmmioStr) { 

pmmioinfo = (PMMIOINFO) pmmioStr; 
pmmioinfo->ulErrorRet = MMIO_SUCCESS; 


switch (wMessage) { 
case MMI0M_0PEN : 

printf(“ MMI0M_0PEN received by dummy I/O procedure\n”); 
break; 

case MMI0M_CL0SE : 

printf(“ MMI0M_CL0SE received by dummy I/O procedure\n”); 
break; 
default : 

printf(“ MSG# %d received by dummy I/O procedure\n”,wMessage); 
break; 

} /* end switch */ 
return MMI0_SUCCESS; 


Figure 4-5. Temporary I/O Procedure Installation Sample (Continued) 

In method 2, an application can semi-permanently install an I/O procedure 
into the MMIO manager table of loaded I/O procedures. Using the 
mmioInstalllOProc API, the entry point of an I/O procedure ( plOProc para¬ 
meter) and a FOURCC identifier ( fccIOProc parameter) are passed to the 
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MMIO manager to install the I/O procedure. After being installed, the I/O pro¬ 
cedure can be used only by the application that installed it, and only until the 
application terminates. An application must install the I/O procedure each 
time it is run. This method of installation makes the I/O procedure available to 
the OS/2 process that installed the I/O procedure. The MMIO manager internal 
I/O procedure table is a per process table, meaning each process has its own 
table. This will prevent other multimedia applications from being able to use 
it. The mmioInstalllOProc API can be used to find and remove I/O proce¬ 
dures that were installed. The ulFlags parameter is used to specify the opera¬ 
tion: MMIO.INSTALLPROC, MMIO_REMOVEPROC, or MMIO.FIND- 
PROC. The mmioInstalllOProc API does not prevent an application from 
installing more than one I/O procedure with the same FOURCC identifier. 
The following code sample shows the semi-permanent installation of a dummy 
I/O procedure that happens to be a routine within an application. 


INT main( VOID ) 

{ 

ULONG 

HMMIO 

MMIOINFO 

FOURCC 

PMMIOPROC 

system(“cls”); 
printf(“\n\n”); 
printf (“ START: 
Sample\n\n”); 


ul Rc = 0; 
hmmio = 0; 
mmioinfo; 
fccIOProc; 
pmmioproc; 


Semi-permanent Install 


of Dummy I/O Procedure 


/* Install the Dummy I/O procedure */ 

fccIOProc = mmioFOURCC(‘m’,*i’, ’n’,*e*): /* My I/O Proc Identifier */ 
pmmioproc = IOProc_Entry; /* My I/O Proc entry point */ 

pmmioproc = mmiolnstal1I0Proc(fccI0Proc, pmmioproc, 

MMI0_INSTALLPROC); 


/* Error if NULL returned or I/O procedure address is incorrect */ 
if (!pmmioproc || pmmioproc != IOProc_Entry) { 

/* error */ 

printf(“Error on mmiolnstal1IOProcXn”); 
goto end; 


/* Test the installation, Open file using the Dummy */ 

/* I/O procedure to access this file. */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

Figure 4-6. Semi-permanent I / O Procedure Installation Sample 
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mmioinfo.fccIOProc = fccIOProc; /* Skip identify, use my I/O proc */ 
hmmio = mmioOpen(“e: Wmmos2\\moviesWmacaw.avi ”, 

&mmioinfo, MMI0_READ); 

/* Check if error occurred */ 
if (!hmmio) { 

/* error */ 

printf(“Error on mmioOpen\n”); 
goto end; 


end: 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

printf (“ END: Semi-permanent Install of Dummy I/O Procedure Sample\n\n”); 

return ulRc; 

} /* End of main */ 


j •k'k-k-k-k-k-k-k'k-k-k'k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/* Dummy I/O procedure entry point */ 

/***•*• *******************************/ 

LONG API ENTRY IOProc_Entry ( PVOID pmmioStr, 

WORD wMessage, 
LONG IParaml, 
LONG !Param2 ) 


PMMIOINFO pmmioinfo; 

/* Clear the error return before anything */ 
/* happens to ensure valid results. */ 
if (pmmioStr) { 

pmmioinfo = (PMMIOINFO) pmmioStr; 
pmmioinfo->ulErrorRet = MMI0_SUCC ESS; 


switch (wMessage) { 
case MMI0M_0PEN : 

printf(“ MMICM_OPEN received by dummy I/O Proc\n”); 
break; 

case MMI0M_GETF0RMATINF0 : 

printf(“ MMI0M_GETF0RMATINF0 received by dummy I/O Proc\n”); 
break; 

case MMI0M_CL0SE : 

printf(“ MMI0M_CL0SE received by dummy I/O Proc\n”); 
break; 
default : 

Figure 4-6. Semi-permanent I / O Procedure Installation Sample (Continued) 
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printf(“ MSG# %d received by dummy I/O Proc\n”.wMessage); 
break; 

} /* end switch */ 
return MMIO_SUCCESS; 

} 


Figure 4-6. Semi-permanent I / O Procedure Installation Sample (Continued) 

In method 3, an application can permanently install an I/O procedure into 
the MMPMMMIO.INI file. This would typically be done when an application is 
installed in the system, not at application run time. Each time a multimedia 
application that uses MMIO is started, the I/O procedures listed in the MMP¬ 
MMMIO.INI are added to the MMIO manager internal, per process, I/O proce¬ 
dure table. This process allows an I/O procedure to be used by any application 
without the need to use method 1 or 2 to install the I/O procedure at applica¬ 
tion run time. To install an I/O procedure using this method, it is a require¬ 
ment that the I/O procedure must be contained within a DLL. A DLL can con¬ 
tain more than one I/O procedure. The mmioIniFileHandler API passes a 
pointer to a MMINIFILEINFO data structure, which contains the informa¬ 
tion to be stored in the MMPMMMIO.INI file. 


typedef 

struct .MMINIFILEINFO 1 

[ /* 

mminifi1einfo 

*/ 

FOURCC 

fccIOProc; 

/* 

IOProc identifier 

*/ 

CHAR 

szDLLName[260]; 

/* 

DLL name string 

*/ 

CHAR 

szProcName[32]; 

/* 

Procedure name string 

*/ 

ULONG 

ul FI ags; 

/* 

Flags for Preload 

*/ 

ULONG 

ulExtendLen; 

/* 

Length of ext fields 

*/ 

ULONG 

ulMediaType; 

/* 

Media type 

*/ 

ULONG 

ulIOProcType; 

/* 

Type of IOProc 

*/ 

CHAR 

szDefExt[4]; 

/* 

Default file extension 

*/ 


} MMINIFILEINFO; 


The mmioIniFileHandler API can also be used to find and remove I/O pro¬ 
cedures that were installed. The search criteria for the installing, removing, 
and finding can be modified to search based on particular fields of the 
MMINIFILEINFO structure. The ulFlags parameter is used to specify the 
operation and search criteria: 
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MMIO_INSTALLPROC This flag adds an I/O procedure to the end of the 

MMPMMMIO.INI file. If an existing entry in the 
table matches the new entry, the new entry 
replaces the existing entry. An entry match is 
determined by specifying 0 or more of the match 
flags. If none are specified, the default is to 
match on the FOURCC code. 

MMIO_REMOVEPROC This flag deletes a matching entry from the 

MMPMMMIO.INI file. An entry match is deter¬ 
mined by specifying 0 or more of the match flags. 
If none are specified, the default is to match on 
the FOURCC code. 

MMIO_FINDPROC This flag finds a matching entry from the MMP¬ 

MMMIO.INI file. This fills the remainder of the 
MMINIFILEINFO structure passed in the 
pmminifileinfo parameter. An entry match is 
determined by specifying 0 or more of the match 
flags. If none are specified, the default is to 
match on the FOURCC. Note: If 
MMIO.MATCHFIRST is set, then 
MMIOJFINDPROC does not default to the 
FOURCC. 

MMIO_MATCHFIRST This flag finds the first entry in the MMPMM¬ 
MIO.INI file if no match flags are specified. 
Otherwise, it finds the first entry that matches 
the contents of the fields specified by the match 
flags. In either case, the MMINIFILEINFO 
structure is returned. 

MMIO_MATCHNEXT If no match flags are specified, this flag finds the 

next entry in the MMPMMMIO.INI file following 
the entry (MMINIFILEINFO structure) passed 
in pmminifileinfo parameter. If match flags are 
specified, this flag finds the next entry that 
matches the search criteria specified by the flags. 
In either case, the MMINIFILEINFO structure 
is returned. 

MMIOJMATCHFOURCC Use the FOURCC code (fccIOProc field 

of MMINIFILEINFO structure) as a search 
criteria. 
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Use the DLL Name ( szDLLNameO field 
of MMINIFILEINFO structure) as a search 
criteria. 

Use the case-sensitive procedure name 
C szProcNameU field of MMINIFILEINFO struc¬ 
ture) as a search criteria. 

Use the drive or path given with the DLL name 
(szDLLNameU field of MMINIFILEINFO struc¬ 
ture), otherwise use only the base file name. This 
allows DLLs with the same base name to be 
loaded from different directories. 

When using the MMIO_FINDPROC flag, some fields of the MMINIFILE¬ 
INFO structure may not be returned. In these cases, use the 
mmioGetFormats API to query I/O procedure information like media type. 
The following code sample shows the permanent installation of the AVI file for¬ 
mat (AVIO) I/O procedure. AVI is a movie file format and is discussed later in 
this chapter. For the sake of this sample, the AVIO is first found and removed 
and then reinstalled using mmioIniFileHandler. If the system has system 
sounds enabled, then the machine should be rebooted after installing or remov¬ 
ing an I/O procedure for the change to take effect. If system sounds are not 
enabled, then terminating any running multimedia applications will allow the 
changes to take effect. 


MMIOJMATCHDLL 

MMIO.MATCH- 

PROCEDURENAME 

MMIOJFULLPATH 


ULONG 

ULONG 

HMMIO 

MMINIFILEINFO 

MMIOINFO 

FOURCC 


ul Rc = 0 ; 
ul FI ags; 
hmmio = 0; 
mminifi1einfo; 
mmioinfo; 
fccIOProc; 


system(“cls”); 
printf(“\n\n”); 

printf (“ START: Find, Remove, and Install an I/O Procedure permanently 
Sample\n\n”); 


fccIOProc = mmioFOURCC(‘ A ’, ’ V ’, ’ I ’ , ’ '); 


/* Find the AVIO I/O procedure. Match the FOURCC exactly */ 
memset(&mminifi1einfo, ‘\0’, sizeof(MMINIFILEINFO)); 
mminifi1einfo.fccIOProc = fccIOProc; /* Exact match for AVIO */ 
ulFIags = MM 10_FINDPROC; 

ulRc = mmiolniFi1eHandler(&mminifi1einfo, ulFIags); 


Figure 4-7. Permanent I/O Procedure Installation Sample 
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/* Check if error occurred */ 
if (ulRc) { 

/* error */ 

printf(“Error on mmiolniFi1eHandler(Find)\n”); 
goto end; 


/* Remove the AVIO I/O procedure */ 
ulFlags = MM 10_REM0VEPROC; 

ulRc = mmiolniFi1eHandler(&mminifi1einfo, ulFlags); 

/* Check if error occurred */ 
if (ulRc) { 

/* error */ 

printf(“Error on mmiolniFi1eHandler(Remove)\n”); 
goto end; 


/**N0TE****************************************************************/ 


/* If your system has system sounds enabled, then at this point */ 
/* Reboot your machine. Otherwise, terminate any running multimedia */ 
/* applications before the removal takes affect. */ 


/* Verify it has been removed by trying */ 
/* to open a file using this I/O procedure */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 


mmioinfo.fccIOProc = fccIOProc; /* Skip identify, use AVIO I/O Proc*/ 
hmmio = mmio0pen(“e:\\mmos2\\movies\\macaw.avi”, &mmioinfo, 

MMI0_READ+MMI0_N0IDENTIFY); 

/* Check if we were successful in opening the file. */ 

/* We should not be able to open it. */ 

if (hmmio) { 

/* error */ 

printf(“Error, Remove did not work, file was open with the AVIO I/O pro¬ 
cedure .\n”); 

goto end; 

1 


/* Install the AVIO I/O procedure */ 
mminifi1einfo.fccIOProc = fccIOProc; 
strcpy(mminifi1einfo.szDLLName,“AVIO”); 
strcpy(mminifi1einfo.szProcName,”IOProc_Entry”); 
mminifi1einfo.ulMediafype = MMI0_M ED IATY P E_M0VIE; 


Figure 4-7 . Permanent I/O Procedure Installation Sample (Continued) 
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mminifi1einfo.ulIOProcType = MM 10_10PR0C_FILEFORMAT; 
ulFlags = MM 10_I N STA L L P ROC ; 

ulRc = mmiolniFi1eHandler(&mminifi1einfo, ulFlags); 

/* Check if error occurred */ 
if (ulRc) { 

/* error */ 

printf(“Error on mmiolniFi1eHandler(Instal1 )\n”); 
goto end; 


/**N0TE****************************************************************/ 


/* If your system has system sounds enabled, then at this point */ 
/* Reboot your machine. Otherwise, terminate any running multimedia */ 
/* applications before the installation takes affect. */ 


/* Try to open a file using this I/O procedure */ 

/* to make sure it was installed */ 

memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 


mmioinfo.fccIOProc = fccIOProc; /* Skip identify, use AVIO I/O Proc*/ 
hmmio = mmioOpen( M e:\\mmos2WmoviesWmacaw.avi”, &mmioinfo, 

MMI0_READ+MMI0_N0IDENTIFY); 

/* Check if we were successful in opening the file. */ 

/* We should be able to open it. */ 

if (!hmmio) { 

/* error */ 

printf(“Error on mmioOpen\n”); 
goto end; 


end; 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

printf (" END; Find, Remove, and Install an I/O Procedure permanently 
Sample\n\n”); 


Figure 4-7. Permanent I /O Procedure Installation Sample (Continued) 

I/O Procedure Format Information 

It is sometimes useful for an application to be able to query the I/O procedures 
(both file format and storage system) installed in the system to determine if a 
necessary I/O procedure has been installed. Three APIs can be used for gather- 
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ing information about I/O procedures: mmioQueryF ormatCount , 
mini oGet For mats , and mmioGetF ormatN ame. The mmioQuery- 
FormatCount API is used to determine the number of I/O procedures that 
match a search criteria. The mmioGetF or mats API is used in the same 
manner, but this API returns information about the I/O procedures instead of 
the number of I/O procedures. This information is returned in a 
MMFORMATINFO data structure. 


typedef struct _MMF0RMATINF0 { /* mmformatinfo */ 

ULONG ulStructLen; /* Length of this structure */ 

FOURCC fccIOProc; /* IOProc identifier */ 

ULONG ulIOProcType; /* Type of IOProc */ 

ULONG ulMediaType; /* Media Type */ 

ULONG ulFlags; /* IOProc capability flags */ 

CHAR szDefaul t Format Ext [si zeof (FOURCO+l]; /* File extension */ 

ULONG ulCodePage; /* Code Page */ 

ULONG ulLanguage; /* Language */ 

LONG INameLength; /* length of identifier string */ 

} MMFORMATINFO; 


There are several types of I/O procedures. Each type of I/O procedure defines 
a standard set of messages that it can support. This set may only be 

a subset of the possible operations; many messages are optional. For example, 
the editing operations are optional. To determine if an I/O procedure supports 
the message you want to use, use the mmioGetFormats API to query the I/O 
procedure capability flags. The capability flags are contained in the ulFlags 
field of the MMFORMATINFO data structure. These capabilities indicate the 
type of operations that an I/O procedure can perform. There is a standard set 
of capabilities defined: 


Reading and Writing Flags: 

MMIO_CANREADTRANSLATED 

MMICLCANWRITETRANSLATED 

MMIO_CANREADWRITETRANSLATED 

MMICLCANREADUNTRANSLATED 

MMIO_CANWRITEUNTRANSLATED 

MMIO_CANREADWRITEUNTRANSLATED 

MMIO_CANMULTITRACKREADTRANSLATED 

MMIO_CANMULTITRACKREADUNTRANSLATED 

MMIO_CANMULTITRACKWRITETRANSLATED 

MMIO_CANMULTITRACKWRITEUNTRANSLATED 

MMICLCANTRACKREADTRANSLATED 

MMICLCANTRACKREADUNTRANSLATED 

MMIO_CANTRACKWRITETRANSLATED 

MMIO_CANTRACKWRITEUNTRANSLATED 
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Seeking Flags: 

MMIO_CANSEEKTRANSLATED 

MMIO_CANSEEKUNTRANSLATED 

MMIO_CANTRACKSEEKTRANSLATED 

MMIO_CANTRACKSEEKUNTRANSLATED 

Editing Flags: 

MMIO_CANINSERTUNTRANSLATED 
MMICLCANINSERTTRANSLATED 
MMIO_CANSAVEUNTRANSLATED 
MMIO_CANSAVETRANSLATED 


These flags mostly indicate whether the I/O procedure can read and/or write 
files, operate on translated or untranslated data, support editing operations, 
and support multi-track operations. For example, some I/O procedures may 
only be able to read data files and not write to, or be able to create, new data 
files. Non-standard operations or I/O procedure-specific operations typically 
are not listed in the capabilities flag. 

For flags that indicate a translated operation, translation refers to the abili¬ 
ty of the I/O procedure to convert the data in the file to a standard form. I/O 
procedures of the same media type will have the same translated form. 
Therefore, translation provides the capability to convert data in one format to 
another format, by having a common form of the data that can be interchanged 
between two I/O procedures. 

In the case of multi-track support, some file formats (e.g., movie files) can 
support multiple tracks of data. A track of data is a temporally sequential 
stream of data of one media type. The data within a track does not necessarily 
need to be physically sequential or continuous—it depends on the file format. 
For example, most movie files have a video track and an audio track. The file 
formats that support multiple tracks have the corresponding capability flags 
set. 

The mmioGetFormatName API retrieves the format name associated with 
a particular I/O procedure. The format name is a null-terminated text string 
that describes the I/O procedure. This call is useful for applications that dis¬ 
play lists of I/O procedures by name but do not want to be “hard-coded” to a 
specific set of I/O procedures. Some file format I/O procedures do not have for¬ 
mat names. The storage system I/O procedures shipped with MMPM/2 do not 
have format names, therefore, do not assume all I/O procedures are required to 
provide format names. When using this API, make sure the INameLength field 
of MMFORMATINFO is filled in with the length of the buffer passed in the 
pszFormatName parameter. This information can be queried by using the 
mmioIdentifyFile API to fill in the MMFORMATINFO structure. 

Using the mmioQuery For mat Count and mmioGetFormats APIs, it is 
possible to set criteria for the search of I/O procedures by using the 
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ulMediaType or fccIOProc fields of the MMFORMATINFO structure. The 
ulMediaType field can be used to specify one media type, not multiple media 
types. In other words, the matching is an exact match instead of an inclusion 
match for this field. This also applies to the fccIOProc field. Therefore, if you 
are searching for multiple media types, multiple calls to the MMIO APIs is 
required. The alternative is to query all of them and do your own matching 
from this list. 

The following code sample shows how to query the number of I/O procedures 
installed and to then use this information to query the list of I/O procedures 
installed. The sample will then query and display the names of each I/O 
procedure. 


ULONG ulRc = 0; 

MMFORMATINFO mmformatinfo; 

PMMFORMATINFO pmmformatinfo List = 0; 

PMMFORMATINFO pmmformatinfoCurr; 

LONG 1NumFormats = 0; 

LONG 1NumFormatsRead = 0; 

LONG 1NumBytesRead = 0; 

ULONG i; 

PSZ pszFormatName = 0; 

PSZ pszFOURCC = 0; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Query 1/0 Procedures installed in the system Sample\n\n”); 

/* Query for all 1/0 Procedures */ 

/* installed in this system */ 

memset(&mmformatinfo, ‘\0’, sizeof(MMFORMATINFO)); 
mmformatinfo.ulStructLen = sizeof(MMFORMATINFO); 

/* Do not specify the ulMediaType field because each media type */ 

/* must be searched on a separate call to mmio. Therefore, it is*/ 

/* probably better to search for all IOProcs and do the match */ 

/* yourself within this list that gets returned. */ 

ulRc = mmioQueryFormatCount( &mmformatinfo, &1NumFormats, 0, 0); 

/* This API may fail on some systems when the MMPMMMI0.INI file contains */ 

/* entries for 1/0 procedures that no longer exist in the LIBPATH. So, */ 

/* when this fails, try specifying a media type. When the ulMediaType */ 

/* field is set, the mmioQueryFormatCount will return only IOProcs of */ 

/* that media type. */ 

Figure 4-8. Query I/O Procedure Format Information Sample 
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if (ulRc || INumFormats == 0) { 

/* error */ 

printf (“mmioQueryFormatCount: Error or no IOProcs-rc=%d,#formats=%d\n”, 
ulRc, INumFormats); 

/* When query for all I/O procedure fails, */ 

/* try a specifc media type instead */ 

mmformatinfo.ulMediaType = MMI0_MEDIATYPE_AUDI0 ; 

ulRc = mmioQueryFormatCount! &mmformatinfo, &1NumFormats, 0, 0); 

if (ulRc || INumFormats == 0) { 

/* error */ 

printf(“mmioQueryFormatCount:Error or no IOProcs- 
rc=%d,#formats=%d\n”, 

ulRc, INumFormats); 
goto end; 

} 


printf (“mmioQueryFormatCount: Successful - rc=%d, #formats=%d\n”, 
ulRc, INumFormats); 
pmmformatinfoList = 

(PMMF0RMATINF0) malloc (sizeof(MMFORMATINFO) * INumFormats); 
mmformatinfo.ulIOProcType = MMI0_10PR0C_FILEFORMAT; //TEMP HACK 
ulRc = mmioGetFormats(&mmformatinfo, INumFormats, (PVOID)pmmformatinfoList, 
&1NumFormatsRead, 0, 0); 

/* The mmformatinfo.ulIOProcType field is updated on */ 

/* return from this call. */ 

if (ulRc || 1NumFormatsRead == 0) { 

/* error */ 

printf (“mmioGetFormats: Error or no IOProcs - rc=%d, #formats=%d\n”, 
ulRc, 1NumFormatsRead); 
goto end; 

} else { 

printf (“mmioGetFormats: Successful - rc=%d, #formats=%d\n”, 
ulRc, 1NumFormatsRead); 

} /* endif */ 

/* Loop through all format info structs and get the name to display */ 
for (i=0, pmmformatinfoCurr = pmmformatinfoList; 
i<1NumFormatsRead; 
i++,pmmformatinfoCurr++) { 

/* The MEM, DOS, BND, CF storage system 1/0 procedures */ 

/* don’t have format names, therefore ignore them */ 
if (pmmformatinfoCurr->lNameLength) { 

pszFormatName = (PSZ) malloc (pmmformatinfoCurr->lNameLength+1); 


Figure 4-8. Query I / O Procedure Format Information Sample (Continued) 
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ulRc = mmioGetFormatName( pmmformatinfoCurr, pszFormatName, 

&1NumBytesRead, 0, 0); 

if (ulRc || 1NumBytesRead != pmmformatinfoCurr->lNameLength) { 

/* error */ 

printf (“mmioGetFormatName: Error or no name-rc=%d f #Bytes=%d\n”, 
ulRc, 1NumBytesRead); 

} else { 

pszFormatName[lNumBytesRead] = ‘\0’; 

printf (“mmioGetFormatName: Successful - rc=%d, #Bytes=%d\n”, 
ulRc, 1NumBytesRead); 
printf (“Name=%s\n”, pszFormatName); 

} /* endif */ 

if (pszFormatName) 

free((PVOID)pszFormatName); 

} else { 

printf (“This IOProc has no Format name: %s\n”, 
pmmformatinfoCurr->szDefaultFormat Ext); 

} /* endif */ 

pszFOURCC = (PSZ) &pmmformatinfoCurr->fccIOProc; 
printf( M FOURCC = \”%c%c%c%c\” \n”,pszFOURCCEO],pszF0URCC[l], 

pszF0URCC[2],pszFOURCC[3]); 
printf(“ I/O Procedure Type = \”%s\” \n”, 

(pmmformatinfoCurr->ulI0ProcType==MMI0_I0PR0C_ST0RAGESYSTEM)? 
“StorageSystem”:”Fi1eFormat”); 

printf(“ Media Type = %x \n”,pmmformatinfoCurr->ulMediaType); 
printf(“ Capabilities Flags = %x \n”,pmmformatinfoCurr->ulFIags); 
printf(“ Extension = \”%s\” \n”,pmmformatinfoCurr- 
>szDefaultFormat Ext); 
printf(“\n”); 

} /* endfor */ 


end: 

if (pmmformatinfoList) 

free((PVOID)pmmformatinfoList); 

printf (“ END: Query I/O Procedures installed in the system Sample\n\n”); 


Figure 4-8. Query I/O Procedure Format Information Sample (Continued) 
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FILE FORMAT I/O PROCEDURES 


A file format consists of a structured way to lay out data within a file. This 
structure is typically called a “wrapper” because it wraps the data and provides 
a way to store data within a file. This data can include digital audio, bit-map 
image, digital video, MIDI, text, and many other types of data. Some file for¬ 
mats can contain multiple data types (e.g., movie files). The term data type is 
synonymous with media type defined earlier in this chapter. 

Many types of file formats are available today. Each format has its own head¬ 
er definitions and data layout. In fact, this is one of the primary reasons for hav¬ 
ing a multimedia I/O subsystem—to provide file format independence to applica¬ 
tions and the other subsystems of MMPM/2. Most applications do not need to 
write code to deal with each of these file formats directly. MMIO hides the intri¬ 
cacies of each file format and allows an application to program to a general inter¬ 
face that is common across all of the formats. For each file format, a file format 
I/O procedure would exist that can be used to process files of that type. 

A file format procedure is an I/O procedure that provides services to manip¬ 
ulate data at the element level, with each procedure handling a different ele¬ 
ment type such as audio, image, or MIDI. An element can be considered a data 
file, or section of a data file that contains data of a particular media type. A file 
format I/O procedure unwraps the data within the object (file) and presents the 
data itself to an application. This data can be presented, in most cases, in a 
standard form or in the native form as it exists in the file. A file format proce¬ 
dure will probably call a storage system I/O procedure for two reasons. It can 
call to obtain data within a file containing multiple elements or to process a 
wrapped object other than a typical file system data object (file). A file format 
I/O procedure may also call one or more CODEC procedures to compress the 
data as it is written to a file or decompress the data as it is read from the file. 
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Figure 4-9. I/O Procedure Communication 

For file format I/O procedures, a basic set of MMIO_ messages must be sup¬ 
ported. These include support for the following MMIO APIs: mmioOpen, 
mmioClose , mmioIdentifyFile, mmioGetFormatName, mmioGetFormats , 
mmioGetHeader , and mmioQueryHeaderLength. The MMIO Manager 
maps these API calls into message calls to a particular I/O procedure. There 
are really no rules that state the minimum set of messages that must be sup¬ 
ported by an I/O procedure. The following messages are typically expected to be 
supported by applications and other subsystems within MMPM/2: 
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Basic Messages: 

MMIOM.OPEN 

MMIOM_CLOSE 

MMIOMJDENTIFYFILE 

MMIOM.GETFORMATNAME 

MMIOM.GETFORMATINFO 

MMIOM_GETHEADER 


This message requests that a file should 
be opened or deleted. It is passed to the 
I/O procedure on an mmioOpen call. 

This message requests that a file opened 
with mmioOpen should be closed. It is 
passed to the I/O procedure on an 
mmioClose call. 

This message queries an I/O procedure to 
determine if it can process a particular 
file. It is passed to the I/O procedure on 
an mmioIdentifyFile call. This message 
does not require that the file be opened 
by mmioOpen. 

This message requests the format name 
for an I/O procedure. It is passed to the 
I/O procedure on an mmioGet- 
FormatName call. This message does 
not require that the file be opened by 
mmioOpen. 

This message requests format informa¬ 
tion and the capabilities of an I/O proce¬ 
dure. It is passed to the I/O procedure on 
an mmioGetFormats call. This message 
does not require that the file be opened 
by mmioOpen. 

This message requests that the I/O proce¬ 
dure return a media specific header. The 
specific header depends on the type of I/O 
procedure and current track setting, in 
the case of multiple tracks. This header 
can be a raw header or a translated head¬ 
er. This message is passed to the I/O pro¬ 
cedure on an mmioGetHeader call. 
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MMIOM.QUERYHEADERLENGTH This message requests that the I/O proce¬ 
dure return the size of a media specific 
header. The specific header depends on 
the type of I/O procedure and current 
track setting, in the case of multiple 
tracks. This header can be a raw header 
or a translated header. This message is 
passed to the I/O procedure on an 
mmioQueryHeaderLength call. 

All other messages are optional and usually based on the media type of the 
I/O procedure. For example, movie I/O procedures must support the multi¬ 
track messages, MMIOM_MULTITRACKREAD and MMIOM_MULTI- 
TRACKWRITE, instead of the typical MMIOM_READ and 
MMIOM_WRITE messages in order to be used by MMPM/2. The 
mmioGetFormats API can be used to query whether some of the optional 
message are supported, as discussed in the previous section. Most of the 
optional messages are discussed in the rest of this chapter. They typically fall 
into several categories, such as, Header setting APIs and messages, I/O opera¬ 
tion APIs and messages, editing messages, multi-track messages, attribute 
setting APIs and messages, seeking APIs and messages, and CODEC access 
messages. 

Resource Interchange File Format (RIFF) 

The MMIO subsystem has built-in support for the RIFF or Resource 
Interchange File Format. The Resource Interchange File Format is a tagged 
file structure and a general specification upon which media specific file formats 
can be built. It provides a set of concepts and APIs that can be used to easily 
build new file formats. The MMIO manager provides a set of navigation APIs 
that allow an application to traverse through the RIFF format. The RIFF spec¬ 
ification is a tool that can be used to develop new file formats quickly . For 
example, the AVI movie file format is RIFF based. AVI or Audio Video 
Interleaved is a standard movie file format used by MMPM/2. RIFF forms of 
audio, MIDI, and image file formats have been defined. RIFF is a joint stan¬ 
dard adopted by IBM and others for multimedia data. 

The AVI movie file format supports files that have a video track and one or 
more audio tracks. The video track contains all of the video data for the movie 
and the audio track(s) contain all of the audio data for the movie. Currently, 
MMPM/2 supports one track of video and one of audio in each file. The inter¬ 
faces are defined such that multiple tracks of any one media type are possible 
within the same file. 
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The basic building block of a RIFF file is a chunk. A chunk is a data area 
with an identifier and a type. RIFF files are made of a series of chunks. There 
are different types of chunks, depending on the chunk ID. A chunk ID is a 
FOUR-Character Code (FOURCC) that identifies the representation of a 
chunk data. To an application, the advantage of a file format like RIFF is that 
applications can access the chunks in a file that it can identify and ignore the 
ones that it can not. This gives a certain flexibility to the way that information 
is stored. MMIO provides the following functions to locate, create, enter, exit, 
and access chunks within a file: 

RIFF APIs and Messages: 

mmioCreateChunk This API creates a chunk in a RIFF file that was opened 

by mmioOpen. 

mmioAscend This API ascends out a chunk in a RIFF file that was 

descended into by mmioDescend or created by 

mmioCreateChunk. 

mmioDescend This API descends into a RIFF file chunk beginning at 
the current file position, or searches for a specified 
chunk. 

RIFF has a concept of a compound file format. Using the RIFF structure, a 
user can basically imbed multiple files within a single file. This “wrapper” for 
files is called a bundled file. The MMIO Manager provides a set of APIs to cre¬ 
ate and manipulate these kinds of files. Refer to the Compound File Storage 
System section of this chapter for a detailed look at bundled files. 

Some File Formats Available for MMPM/2 

With each release of OS/2 and MMPM/2, new file formats are added as they 
become popular. Some of these are provided with MMPM/2, and some are writ¬ 
ten by users of MMPM/2 and provided on bulletin boards or other forums. The 
list of available I/O procedures is always growing. Some PC standard file for¬ 
mats are RIFF-based, while other file formats are not RIFF-based. Some file 
formats are adopted from file formats used on other hardware platforms. 
Amiga and Apple audio file formats are a good example of this. MMPM/2 has 
the ability to play some of these audio files. Refer to Table 4-1 for a list of some 
of the available file formats. 

In general, FOURCC and media type are concepts from the RIFF file format 
that MMPM/2 adopted as the standard ways of uniquely identifying file for¬ 
mats. These are extendible to other file formats, because the mapping takes 
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place in the I/O procedure and the MMPMMMIO.INI file entry information 
and not the actual file. So the actual file format does not need to understand 
FOURCCs or media types. 


Media Type 

I/O 

Procedure 

FOURCC 

Extension 

Description 

Available From 

RIFF 

Audio 

AVC Audio 

AVC A 

._AU, ._AD 

Supports IBM Audio Visual 
Connection (AVC) digital audio 
files of type ADPCM and native 
ACPA formats. 

MMPM/2 1.0 or 
later 

N 

Audio 

CLIVOC 

VOC 

.VOC 

Supports Creative Labs Voice 
files. 

MMPM/2 1.1 or 
later 

N 

Audio 

RIFF 

Waveform 

WAVE 

.WAV 

Supports RIFF waveform audio 
files of type PCM, ADPCM, 

IBM Mu-Law, and A-Law 

MMPM/2 1.0 or 
later 

Y 

Audio 

AIFF 

Waveform 

AIFF 

.AIF 

Supports AIFF waveform 
digital audio files. 

OS/2 Warp 

Bonus Pack 

N 

Audio 

Amiga IFF 

IFF 

.IFF 

Supports Amiga IFF digital 
audio files. 

OS/2 Warp 

Bonus Pack 

N 

Audio 

Unix SND 

SND 

.SND 

Supports UNIX (NeXT/Sun) 

SND digital audio files. 

OS/2 Warp 

Bonus Pack 

N 

MIDI 

MIDI, 

RIFF MIDI 

MIDI, 

RMID 

.MID 

Supports MIDI format 0 and 1 
data in native or RIFF file. 

MMPM/2 1.0 or 
later 

Y 

Image 

AVC Image 

AVCI 

._IM, .!IM, 
._ID 

Supports IBM Audio Visual 
Connection (AVC) digital 
image files. 

MMPM/2 1.0 or 
later 

N 

Image 

DIB 

WI30 

.DIB 

Supports Device Independent 

Bit map image files. 

MMPM/2 1.1 or 
later 

N 

Image 

RIFF DIB 

RDIB 

.RDI 

Supports RIFF Device 
Independent Bit map files. 

MMPM/2 1.1 or 
later 

Y 

Image 

OS/2 1.3 
Bitmap 

OS13 

.BMP 

Supports OS/2 1.3 and 

Windows 3.0 uncompressed 
bitmap image files. 

MMPM/2 1.0 or 
later 

N 

Image 

OS/2 2.0 
Bitmap 

OS20 

.BMP 

Supports OS/2 2.0 and Windows 
3.0 1, 4, 8-bit palettized and 
24-bit RGB bitmap image files. 

MMPM/2 1.1 or 
later 

N 

Image 

M-Motion 

Still 

MMOT 

.VID 

Supports IBM M-Motion/ 
M-Control YUV video still 
image files of the type packed 
12-bit YUV data. 

MMPM/2 1.0 or 
later 

N 


Table 4-1. List of File Format I / O Procedures 






104 Developing Multimedia Applications Under OS/2 


Media Type 

I/O 

Procedure 

FOURCC 

Extension 

Description 

Available From 

RIFF 

Image 

PCX 

PCXC 

.PCX 

Supports compressed PCX 
image files. 

PerfectImage/2 
product or OS/2 

Warp Bonus Pack 

N 

Image 

TIFF 

TFIU, 

TFIC, 

TFMU, 

TFMC, 

TFFC 

.TIF 

Supports uncompressed and 
compressed Intel or Motorola 
TIFF image files and 
compressed TIFF FAX image 
files. 

PerfectImage/2 
product or OS/2 

Warp Bonus Pack 

N 

Image 

TARGA 

TGAU, 

TGAC 

.TGA 

Supports uncompressed and 
compressed TARGA image files. 

PerfectImage/2 
product or OS/2 

Warp Bonus Pack 

N 

Image 

GIF 

GIFC 

.GIF 

Supports compressed GIF 
image files. 

PerfectImage/2 
product or OS/2 

Warp Bonus Pack 

N 

Image 

PhotoCD 

PCD 

.PCD 

Supports PhotoCD image files. 

OS/2 Warp 

N 

Movie 

AVI Movie 

AVI 

.AVI 

Supports Audio Video 

Interleaved movie files. 

MMPM/2 1.1 or 

later 

Y 

Movie 

MPEG -1 

Movie 

MPEG 

.MPG 

Supports MPEG-1 movie files. 

OS/2 Warp 

N 

Movie 

FLC/FLI 

Animation 

flic 

.FLI, .FLC 

Supports FLC/FLI Animation 
files. This I/O procedure also 
will read any audio files in 
same directory with the 
same base name. This creates 

a movie. 

OS/2 Warp 

N 


Table 4-1. List of file Format I / O Procedures (Continued) 


Opening a File 

The mmioOpen API provides the ability to open or create a file. This is a nec¬ 
essary action before a file can be accessed or operations performed on it. There 
are several ways that a file can be opened and accessed using the mmioOpen 
API. The typical way is to pass the file name to mmioOpen. Another way is to 
pass the OS/2 file handle to an open file in the aulInfofO] field of the MMIOIN- 
FO data structure. This can be useful for applications that need to open and 
control access to a file. The following sample shows how to use this feature of 
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mmioOpen. The sample also shows how to use mmioClose to close the MMIO 
handle, and leave the OS/2 handle that was passed in on the mmioOpen open. 


ULONG 

HFILE 

ULONG 

MMIOINFO 

HMMIO 


ul Rc = 0; 
hfile = 0; 
ulAction = 0; 
mmioinfo; 
hmmio = 0; 


system(“cls”); 
printf(“\n\n”); 

printf (“ START: Open with OS/2 file handle Sample\n\n”); 


/* Open the file using OS/2 file services */ 
ulRc = Dos0pen(“e:\\mmos2\\movies\\macaw.avi”, &hfi1e, 
&ulAction, 0, FILE_N0RMAL, FILE_0PEN, 
0PEN_ACCESS_READ0NLY+0PEN_SHARE_DENYN0NE. 
(PEA0P2)NULL); 

if (ulRc) { 

/* error */ 

printf(“Error, DosOpen failed.\n”); 
goto end; 

} 


/* Pass this open file handle to MMIO to use */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.aullnfo[0] = hfile; /* pass the file handle */ 

hmmio = mmio0pen(NULL, &mmioinfo, MMI0_READ); 

/* Check for error */ 
if (!hmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 

end: 

if (hmmio) 

ulRc = mmioClose(hmmio,MMI0_FH0PEN); /* Don't close 0/2 file */ 

if (hfile) 

ulRc = DosClose(hfi1e); 

printf (“ END: Open with OS/2 file handle Sample\n\n”); 


Figure 4-10. Opening a File Sample 
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Opening a Memory File 

The mmioOpen API can also be used similarly to open memory files. A memo¬ 
ry file is an in-memory version of a file. This can be an application-generated 
file or it can be a file read from secondary storage (e.g., disk drive). This can be 
useful in the case where an application already has the file loaded in memory. 
Using memory files can be more efficient than reading the same file from disk, 
but it also requires more memory. Some applications may find memory files 
useful if they need direct access to the data, but also want to take advantage of 
the MMPM/2 streaming subsystem to stream the data in real-time to an out¬ 
put device. Memory files can use memory allocated by the application or by the 
MMIO manager and memory files can be expandable or non-expandable. An 
application can specify the MMIO_ALLOCBUF flag on an mmioOpen call to 
have the MMIO manager allocate the buffer for the memory file. In this case, 
the memory is expandable. Meaning that when MMIO reaches the end of the 
memory buffer on an I/O operation, it expands the memory file buffer by a pre¬ 
defined amount. The application can specify this amount in the aullnfo[0] field 
of MMIOINFO data structure passed on the mmioOpen call. 

The following sample shows how to open a memory file. The pchBuffer field 
of the MMIOINFO must point to the user buffer. The cchBuffer field must con¬ 
tain the buffer length and either the fccIOProc or the fccChildlOProc field 
must contain FOURCC_MEM to indicate that this is a memory file. If the 
fccChildlOProc field is used, the fccIOProc must contain a FOURCC for the 
file format I/O procedure to use to access the data in the memory buffer. 


ULONG 

FILE 

CHAR 

MMIOINFO 
HMMIO 
i nt 


ul Rc = 0 ; 
^stream; 
buffer[8192]; 
mmioinfo; 
hmmio = 0; 
num; 


system(“cls”); 
printf(“\n\n”); 

printf (“ START: Open with memory file Sample\n\n”); 

/* Let’s use an existing file for this sample, Open the file */ 
if ((stream = fopen(“e:\\mmos2\\sounds\\boing.wav”, “rb”)) == NULL) { 
/* Error */ 

printf(“Error, fopen failed.\n”); 
goto end; 


Figure 4-11. Opening a Memory File Sample 
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/* read the file into our memory buffer */ 
num = f reacKbuffer, sizeof(CHAR), 8192, stream); 
if ( num ) { /* fread success */ 

printf( “Number of characters has been read = %i\n”, num ); 
fclose( stream ); 


/* Pass this memory file to MMIO to use */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.pchBuffer = buffer; /* Buffer with memory file */ 

mmioinfo.cchBuffer = num; /* Length of buffer */ 

mmioinfo.fccIOProc = mmioFOURCC(‘W’,’A’,’V’,’E*); 

mmioinfo.fccChi1dIOProc = FOURCC_MEM; /* Must specify memory FOURCC */ 
hmmio = mmioOpen(NULL, &mmioinfo, MM 10_READ); 

/* Check for error */ 
if (!hmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 

end: 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 
printf (“ END: Open with memory file Sample\n\n”); 


Figure 4-11. Opening a Memory File Sample (Continued) 


Buffered File I/O 

The MMIO manager provides services to buffer I/O operations for small reads 
and writes. This buffering can improve performance of applications that do 
many very small reads or writes (less than 4KB in size). Basically, this mecha¬ 
nism works as follows: a buffer of a specific size (for example, 8KB) is allocated, 
and all read (or write) operations are done through this buffer. The buffer is 
initially filled by a file system read on the first application read request. Each 
subsequent read operation extracts data from the buffer until it is empty. 
When empty, the buffer is re-filled in one file system operation. This minimizes 
the number of times that a secondary storage device is accessed and therefore 
increases performance. It is not recommended that this method be used on files 
that are processed through the MCI interface, since a form of buffering is 
already done and larger buffers are typically used. 
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Buffered I/O is transparent to an application, although an application has 
the ability to provide its own buffer to be used for the buffering. There are two 
methods for an application to request buffered I/O: 

1. Use the mmioOpen API and specify the MMIO_ALLOCBUF flag. 

2. Open the file as unbuffered using mmioOpen and then use the 
mmioSetBuffer API to enable buffered I/O. 

To provide its own buffer, an application can specify the 
MMIO_ALLOCBUF flag on the mmioOpen , similar to opening a memory 
file. The difference between an mmioOpen for buffered I/O and opening a 
memory file is that the pszFileName parameter must be NULL in the case of a 
memory file open. The following APIs are provided to facilitate buffered I/O: 

Buffered I/O APIs: 

mmioSetBuffer This API enables or disables buffered I/O, or changes the 
buffer or buffer size, for a file that was opened using 

mmioOpen. 

mmioFlush This API forces the contents of an I/O buffer to be writ¬ 

ten to disk. 

mmioGetlnfo This API retrieves information from the file I/O buffer to 

a file opened for buffered I/O. 

mmioSetlnfo This API changes information on a file I/O buffer of a file 

opened for buffered I/O. 

mmioAdvance This API fills and empties the contents of an I/O buffer of 

a file set up for direct I/O buffer access. 

Format Independent File Headers 

One of the primary reasons for having a multimedia I/O subsystem is to pro¬ 
vide file format independence to applications and the other subsystems of 
MMPM/2. One way that MMIO achieves this is to have a definition of a stan¬ 
dard presentation header for each type of data. Naturally, each file format has 
its own file layout and header structure, but each has common attributes that 
must be present in order to describe the data in the file adequately. For exam¬ 
ple, most audio file formats have a structured way to specify, among other 
things, what the type of data is in the file, what sample rate it is, sample size, 
and so on. These types of attributes are also present in the standard presenta¬ 
tion audio header. The standard presentation headers have been designed to 
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encompass the majority of detailed information necessary to describe the data 
in a file. The headers are purely an intermediate MMPM/2 protocol and may 
not physically exist within the file. A file format may not use all of the fields of 
a standard presentation header. 

These standard headers contain information specific to the media type, but 
in a format that is standard so that applications do not need to understand the 
file format’s specific header. File format I/O procedures can also provide access 
to the “native” file header, called a raw file header. Typically, a file format I/O 
procedure will read the raw header when the file is opened and create a stan¬ 
dard presentation header with information from the raw header. After the file 
is opened, an application can use the mmioQueryHeaderLength , 
mmioGetHeader , and mmioSetHeader APIs to access and manipulate either 
the standard presentation or raw header. 

An ulTranslate field on the MMIOINFO data structure that is passed on 
the mmioOpen API. This flag determines which type of headers, raw or 
standard, that the mmioQueryHeaderLength , mmioGetHeader , and 
mmioSetHeader APIs will use. This field is also used to indicate whether the 
actual data in the file should be translated to a standard interchange form. 
Once the file is opened, the type of headers cannot be changed. 

NOTE: When passing an HMMIO to an MCI device instance, make sure 
that the file was opened with the MMIO^TRANSLATEHEADER flag. 
In most cases, this is required because the MCI devices can not interpret 
native file headers. 

The default setting for translation is to use raw headers. The following flags 
are supported for the ulTranslate field of the MMIOINFO data structure: 

MMIO_NOTRANSLATE No translation of the header or data portion of 

the file into the defined standard presentation 
format will occur for the specified media type. 
This is the default mode. 

MMIO_TRANSLATEDATA The data portion of the file is translated into 

the defined standard presentation format for 
the specified media type. 

MMIO_TRAJVSLATEIIEADER The header portion of the file is translated 

into the defined standard presentation format 
for the specified media type. 

The following series of diagrams show the standard presentation headers, 
and the subheaders contained within each header, of various media types. The 
diagrams are organized by media type. The first three fields of all standard 
presentation headers are always the same. This allows an application to view 



110 Developing Multimedia Applications Under OS/2 


the ulMediaType field and determine the media type and therefore the type of 
header. The application can then make an informed decision as to which head¬ 
er structure to use to reference the header data. This can be of great use to 
applications that need to deal with all types of data. 

MMIO_MEDIATYPEJMAGE 


MMIMAGEHEADER 

MMXDIBHEADER 


XDIBHDR_PREFIX 


BITMAPINFOHEADER2 


_1 

1 

- 

_L 

RGB2 


Figure 4-12. Image Standard Presentation Header 
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The MMIMAGEHEADER is used to access the header information of all 
image file format headers. Some image file formats include: the OS/2 2.0 
bitmap, Audio Visual Connection image, DIB, RDIB, and OS/2 1.3 bitmap 
formats. 

MMIO_MEDIATYPE_AUDIO 


MMAUDIOHEADER 


MMXWAV_HEADER 


WAVE_HEADER 


XWAV_HEADERINFO 


Figure 4-13. Audio Standard Presentation Header 

The MMAUDIOHEADER is used to access the header information of all 
audio file formats. Some audio file formats include: the AVC audio, Sound 
Blaster VOC, and RIFF waveform format. Some of the information in this type 
of header is sample size, samples per second, whether the data is mono or 
stereo. 
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MMIO MEDIATYPE MIDI 


MMMIDIHEADER 


MIDIHEADER 


Figure 4-14. MIDI Standard Presentation Header 

The MMMIDIHEADER is used to access the header information of all 
MIDI file formats. Some MIDI file formats include: the native MIDI and RIFF 
MIDI format. 

MMIO_MEDIATYPE_MOVIE 


MMMOVIEHEADER 

pmmTracklnfoList - 

-J MMTRACKINFO 


Figure 4-15. Movie Standard Presentation Header 
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The MMMOVIEHEADER can be used with all file formats that are catego¬ 
rized as media type movie. A movie typically includes a video track and an 
audio track. The MMMOVIEHEADER contains information related to the 
movie presentation, but nothing specific to the individual tracks of data. The 
MMMOVIEHEADER does contain the number of tracks ( ulNumEntries field) 
in the movie and a list of the media types of these tracks ( pmmTracklnfoList 
field) and other information. Each track has a track header that contains the 
track specific information. These track headers can be accessed by using the 
mmioQueryHeaderLength, mmioGetHeader, and mmioSetHeader APIs. 
For a movie track that contains audio, the MMAUDIOHEADER is used as 
the track header. For a video track, the MMVIDEOHEADER is used as the 
track header. 

MMIO_MEDIATYPE_DIGITALVIDEO 


MMVIDEOHEADER 


GENPAL 

pmmXDIBHeader — 

_ ▼ 

MMXDIBHEADER 

XDIBHDR_PREFIX 


BITMAPINFOHEADER2 


Figure 4-16. Video Standard Presentation Header 

Refer to the Dealing with Multiple Track Files section of this chapter for 
more details on using multiple track files. Currently, movie files are the only 
file formats that utilize the multi-track APIs and messages. 
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The following code sample shows how to use the MMIO header APIs. Note 
that the mmioSetHeader passes the header length as a parameter, this must 
always be equal to the exact size of the header. This may be different from the 
size returned on a mmioGetHeader call, as in the sample. This is because the 
mmioGetHeader in the sample returns some variable length information 
pointed to by the pmmTracklnfoList field of the MMMOVIEHEADER. Note 
that using mmioSetHeader on an existing file will overwrite the existing 
header information with the new information, whether data is written to the 
file on not. 


ULONG 

MMIOINFO 

HMMIO 

PCHAR 

PMMMOVIEHEADER 

LONG 

LONG 


ul Rc = 0 ; 
mmioinfo; 
hmmio = 0; 
pBuffer = 0; 
pMovieHdr = 0; 

1Len = 0; 

1BytesRead = 0; 


system(“cls”); 
printf(“\n\n”); 

printf (“ START: Get and Set Header information for a file Sample\n\n”); 


/* Open the file with header translation */ 
memset(&mmioinfo, ‘\0’ , sizeof(MMIOINFO)); 
mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER; 
hmmio = mmio0pen(“e: Wmmos2\\moviesWmacaw.avi ”, 
&mmioinfo, MMIO_READWRITE); 

/* Check for error */ 
if (!hmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 


/* Query the length of the header - Movie headers */ 
/* can be variable in length */ 
ul Rc = mmioQueryHeaderLength(hmmio, &lLen, 0,0); 
if (ulRc) { 

/* error */ 

printf(“Error, mmioQueryHeaderLength failed.\n”); 
goto end; 


/* Allocate size of header */ 
pBuffer = (PCHAR) malloc (1Len); 


Figure 4-17. Querying Movie Standard Presentation Header Sample 
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/* Get the movie header */ 

ulRc = mmioGetHeader(hmmio, pBuffer, ILen, &!BytesRead, 0,0); 
/* Check for error */ 
if (ulRc) { 

/* error */ 

printf(“Error, mmioGetHeader failed.\n”); 
goto end; 


/* Make changes to the header here!! */ 

pMovieHdr = (PMMMOVIEHEADER) pBuffer; 

/* Set this field to be the largest video frame in file */ 
pMovieHdr->ulSuggestedBufferSize = 4096 L; 

/* Set the movie header */ 

ulRc = mmioSetHeader(hmmio, pBuffer, sizeof(MMMOVIEHEADER), 
&!BytesRead, 0,0); 

/* Check for error */ 

if (ulRc) { 

/* error */ 

printf(“Error, mmioSetHeader failed.\n”); 
goto end; 

} 


end: 

if (pBuffer) 

free((PV0ID)pBuffer); 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

printf(“ END: Get and Set Header information for a file Sample\n\n”); 


Figure 4-17 . Querying Movie Standard Presentation Header Sample 
(Continued) 

Data Translation 

In addition to being able to retrieve the data headers in translated or native 
format, applications can choose to read and/or write the actual data in either 
translated or native formats. I/O procedures of the same media type will have 
the same translated format. Therefore, data translation provides the capability 
to convert data in one format to another format, by having a common format of 
the data that can be interchanged between two I/O procedures. This principle 
is typically used in file format conversion applications. File format conversion 
simply consists of loading translated data from one file and saving it to 
another. 
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The default mode of access is untranslated and it can be selected by passing 
the MMIO_NOTRANSLATE flag or NULL for ulTranslate field of MMIOIN- 
FO on mmioOpen call. This allows the application to read the file data in 
native format. The header and data translation can be controlled separately 
using the flags defined in the last section. Data translation can be enabled on 
an mmioOpen call using the MMIO_TRANSLATEDATA flag. The support 
for data translation is optional and some I/O procedures may not support this 
functionality. Use the mmioGetFormats API to query whether a particular 
file format I/O procedure supports this capability. The following APIs and mes¬ 
sages are affected by the MMIO_TRANSLATEDATA flag: mmioRead , 
mmioWrite , MMIOMJMULTITRACKREAD, MMIOM_MUTITRACK- 
WRITE, mmioSeek , MMIOM.SEEKBYTIME, MMIOM_INSERT, 
MMIOM_SAVE. The following table is a list of media types and the standard 
form of data that applies to that media type. 


Media Type 

Data Translation Types Available 

MMIO_MEDIATYPE_AUDIO 

PCM 11.025, 22.05, 44.1 kHz 

MMIO_MEDIATYPE_IMAGE 

Uncompressed OS/2 1.3 bitmap (24-bit RGB, 

1-, 4-, 8-bit palette) 

MMIO_MEDIATYPE_MIDI 

Format 0 or 1 

MMIO_MEDIATYPE_MOVIE 

Multi-Track, Compressed Video and untrans¬ 
lated audio. Use MMIOM_COMPRESS and 
MMIOM_DECOMPRESS to convert video 
data 

MMIO_MEDIATYPE_DIGITALVIDEO 16- and 24-bit RGB, 4- and 8-bit palette 


Table 4-2. Media Type and Corresponding Translation Types 


The data within a file is actually translated on a mmioRead or mmioWrite 
API call. In the case of mmioRead , the I/O procedure reads the next piece of 
data from the file into a buffer and then converts it to a standard form. This 
standard form is returned in the applications buffer that was passed on the 
mmioRead call. In the case of mmioWrite , the I/O procedure will take the 
data in the application buffer and convert it to native form and then write the 
native form to the file. 

All of the file format I/O procedure types that support translation 
conform to this convention except for movie file formats 
(. MMIO_MEDIATYPE_MOVIE ). Movie files are special in that they do not 
support a translation mode in the same manner that the other media types do. 
Typically, a movie file contains an audio track and a video track. The audio 
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track can contain compressed audio data. Currently, there is no way to trans¬ 
late the audio data in movie files that have compressed audio data. The audio 
data is always returned in native format. 

The video track can contain uncompressed video data, or compressed video 
data of a particular type. Usually, a video CODEC is used to compress and 
decompress the video data of this type. To translate movies between formats, 
an application must use the multi-track messages (MMIOM_MULTITRACK- 
READ and MMIOM_MULTITRACKWRITE) in conjunction with the 
CODEC access messages (MMIOM.COMPRESS and MMIOMJDECOM- 
PRESS). For these reasons, movie file data translation is much more difficult 
then audio or image conversions. 

The following code sample shows how to convert an image in one file format 
to another file format. Audio data translation would be done in a similar fash¬ 
ion. In this sample, the mmioGetHeader and mmioSetHeader APIs are used 
to get and set the headers. The ulTranslate flag must be set on for both the 
input and the output files. The mmioRead API is used to read the translated 
image from the input file and then the mmioWrite API is used to write it to 
the output file. Both files are then closed. The conversion is complete at this 
point. This sample will convert an OS/2 1.3 bit map file to an OS/2 2.0 bit map 
file. To change this sample to convert the image file to GIF, for example, then 
change the code line: 

mmioinfo.fccIOProc = mmioFOURCC(‘O’,’S’,’2’,’0’); 

to the following: 

mmioinfo.fccIOProc = mmioF0URCC(‘G’,’I*,*F*,'C’); 

This will save the image into a GIF file. The file name extension should also 
be changed from “.BMP” to “.GIF.” 


ULONG 

ul Rc = 0; 

LONG 

lRc = 0; 

HMMIO 

hmmioFrom = 0; 

HMMIO 

hmmioTo = 0; 

MMIOINFO 

mmioinfo; 

PCHAR 

pBuffer = 0; 

PMMIMAGEHEADER 

plmageHdr = 0; 

PBYTE 

plmage = 0; 

LONG 

1 Len = 0; 

LONG 

1 NumBytesRead = 0; 

system(“cls”); 


printf(“\n\n”); 


printf (“ START: 

Data Translation S 


Figure 4-18. Image File Conversion Sample 
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/* Open the FROM file and read its headers */ 

/* Open the FROM file with header translation */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER+MMIO_TRANSLATEDATA; 

mmioinfo.aulInfo[3] = MM 10_M ED IATY P E_IMAGE; 

hmmioFrom = mmioOpen(“flamingo.bmp”, &mmioinfo, MMI0_READ); 

/* Check for error */ 
if (!hmmioFrom) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 


/* Query the length of the header */ 

ulRc = mmioQueryFleaderLength(hmmioFrom, &lLen, 0,0); 

if (ulRc) { 

/* error */ 

printf(“Error, mmioQueryFleaderLength failed.\n”); 
goto end; 

} 


/* Allocate size of header */ 
pBuffer = (PCHAR) malloc (1Len); 
plmageHdr = (PMMIMAGEHEADER)pBuffer; 

/* Get the movie header */ 

ulRc = mmioGetHeaderChmmioFrom, pBuffer, ILen, &1NumBytesRead, 0,0) 
/* Check for error */ 

if (ulRc) { 

/* error */ 

printf(“Error, mmioGetFleader failed.\n”); 
goto end; 

} 


/* Create the TO file and write its headers */ 

/* Create the TO file with header translation */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER+MMIO_TRANSLATEDATA; 

mmioinfo.aulInfo[3] = MM10_M EDIATY P E_IMAG E; 

mmioinfo.fccIOProc = mmioF0URCC(‘0’,’S’,’2’,’0’); 

hmmioTo = mmioOpen(“newbmp.bmp”, &mmioinfo, MMI0_CREATE+MMI0_WRITE) 

/* Check for error */ 

if (!hmmioTo) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 


Figure 4-18. Image File Conversion Sample (Continued) 
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goto end; 


/* Set the movie header */ 

ulRc = mmioSetHeader(hmmi 0 T 0 , pBuffer, sizeof(MMIMAGEHEADER), 
&1NumBytesRead, 0,0); 

/* Check for error */ 
if (ulRc) { 

/* error */ 

printf(“Error, mmioSetHeader failed.\n”); 
ulRc = mmioGetLastError(hmmioTo); 
printf(“Error, %1d\n”,ulRc); 
goto end; 


/* Allocate image buffer */ 

1Len = (LONG) pImageHdr->mmXDIBHeader.BMPInfoHeader2.cblmage; 
plmage = (PBYTE) malloc (lLen); 


/* Get the image from the FROM file */ 

1Rc = mmioRead(hmmioFrom, plmage, 1Len); 

/* Check for error */ 
if (1Rc == MMI0_ERR0R) { 

/* error */ 

printf(“Error, mmioRead failed.\n M ); 
goto end; 


/* Anything to write ? */ 
if (IRc > 0) { 

/* Save the image into the TO file */ 

1Len = 1Rc; 

1Rc = mmioWrite(hmmioTo, plmage, ILen); 


end: 

if (pBuffer) 

free((PVOID)pBuffer); 

if (plmage) 

free((PV0ID)pImage); 

if (hmmioFrom) 

ulRc = mmioClose(hmmioFrom,0); 


Figure 4-18. Image File Conversion Sample (Continued) 
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if (hmmioTo) 

ul Rc = mmioClose(hmmi 0 T 0 ,0); 
printf (“ END: Data Translation Sample\n\n”); 


Figure 4-18. Image File Conversion Sample (Continued) 

Dealing with Multiple Track Files 

A common concept in the MMIO subsystem is that of multi-track files. A multi¬ 
track file is a file that contains multiple tracks of data. A track of data is a 
temporally sequential stream of data of one media type. The data within a 
track does not necessarily need to be physically sequential or continuous—it 
depends on the file format. For example, the AVI movie file format I/O proce¬ 
dure supports files that have a video track and an audio track. The video track 
contains all of the video data for the movie and the audio track contains all of 
the audio data for the movie. Currently, the AVI I/O procedure supports one 
track of each. The interfaces are defined such that multiple tracks of any one 
media type are possible within the same file. The AVI movie file format is one 
of the movie file formats supported by MMPM/2. 

For performance reasons, tracks are often interleaved to eliminate unneces¬ 
sary disk seeking during playback of the movie. Interleaving is the process of 
combining multiple tracks of data in an alternating fashion. This is essential 
for movies, since they tend to be extremely large, and they are often distrib¬ 
uted on CD-ROM. CD-ROM device seeks are expensive in time and therefore, 
it is more efficient to read data sequentially from a CD-ROM, than to randomly 
access the CD-ROM, as if it were a hard drive. 

Multiple track files typically have several headers of information. The top 
most header is the file header, which contains general information about the 
file. It also indicates the number of tracks and the type of tracks that are con¬ 
tained with the file. Each track of a multiple track file contains its own stan¬ 
dard presentation header with all essential details necessary to describe the 
data. This includes the identifier of any decompression algorithm that should 
be used to decompress the data. For multiple track files, all of the tracks may 
be in the same file as in AVI movies or in separate file as in the case of 
Autodesk FLC and FLI animation movies. For FLC and FLI movies, the audio 
data is contained in a separate file from the animation data. The FLC/FLI I/O 
procedure will hide this, so that the data appears to be contains within one file. 
This file format is actually not really a multiple track file, but it is presented to 
the application and the other subsystems of MMPM/2 as a multiple track file. 

To deal with multiple track files, MMIO provides a service to set the current 
track, so that individual track information can be retrieved or set using the 
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mmioGetHeader , mmioSetHeader , mmioQueryHeaderLength APIs. 
MMIO also provides services to read and write multiple tracks of data. The 
MMIOM_MULTITRACKREAD and MMIOM_MULTITRACKWRITE mes¬ 
sages are used to access the file for multiple track I/O procedures. These mes¬ 
sages hide any file format specifics from the application and are optimized for 
interleaved files. To determine if an I/O procedure is a multiple track format 
and supports the multi-track APIs and messages, the mmioGetFormats API 
should be used to query the capability flags for the I/O procedure. The 
mmioGetF ormats will return an MMFORMATXNFO data structure that 
contains an ulFlags field. This field will have one or more of the following bit 
flags set if the I/O procedure supports multiple tracks: 


MMIO_CANMULTITRACKREADTRANSLATED 

MMIO_CANMULTITRACKREADUNTRANSLATED 

MMIO_CANMULTITRACKWRITETRANSLATED 

MMIO_CANMULTITRACKWRITEUNTRANSLATED 

MMICLCANTRACKREADTRANSLATED 

MMIO_CANTRACKREADUNTRANSLATED 

MMICLCANTRACKWRITETRANSLATED 

MMIO_CANTRACKWRITEUNTRANSLATED 

MMIO_CANTRACKSEEKTRANSLATED 

MMICLCANTRACKSEEKUNTRANSLATED 


ACCESSING INDIVIDUAL TRACK HEADERS 


Multiple track files will have a file header and one or more track headers. Each 
track contains its own standardized data header with all essential details for 
that track. Any track specific information is contained in this header. Each 
track has a track ID that is used to identify it and a media type that is used to 
describe the type of data in the track. The media type is commonly used to 
indicate which standard presentation header to use for the track. For example, 
a movie track that contains audio, will return information for the track header 
in the standard presentation audio header, MMAUDIOHEADER. For a video 
track, MMVIDEOHEADER is used as the track header. Remember that the 
standard presentation headers are only used if the file was opened with the 
MMIO_TRANSLATE bit flag set. 

The mmioSet API can be used to set the current track number. Once the 
current track is set to a specific track, the header APIs can be used to access 
the header for that track instead of the file header. The MMEXTENDINFO 
data structure passed on the mmioSet call contains a ulFlags field. The field 
must be set to MMIO_TRACK to change the current track. The ulTrackID 
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field must contain the track Id of the track to make the current track. To indi¬ 
cate that the current track should not be set to an individual track, but to the 
file itself, MMIO_RESETTRACKS must be passed in this field. This is the 
case when the application wants to access the file header instead of a track 
header. When a file is opened, the current track is MMIO_RESETTRACKS, 
so the current track only needs to be changed if accessing an individual track. 
The current track affects the following APIs: the header APIs, mmioSeek , 
MMIOM_SEEKBYTIME, mmioRead , mmioWrite , and mmioSet to query 
or associate a CODEC. 

The following code sample shows how to get and set the current track. This 
sample is used in several of the other samples in this chapter. Note that other 
mmioSet operations can occur on the same mmioSet call. Refer to The 
mmioSet API section of this chapter for more details. 


/***************************************************/ 

/* Sets the current track of a multiple track file */ 
/***************************************************/ 

ULONG SetCurrentTrack ( HMMIO hmmio, LONG ITrackNum ) 

{ 

ULONG ulRc; 

MMEXTENDINFO mmextendinfo; 

memset((PVOID)&(mmextendinfo),’\0’, sizeof(MMEXTENDINFO)); 
mmextendinfo.ulStructLen = sizeof(MMEXTENDINFO); 
mmextendinfo.ulFIags = MMIO_TRACK; 
mmextendinfo.ulTrackID = ITrackNum; 

ulRc = mmioSet(hmmio,&mmextendinfo,MMIO_SET_EXTENDEDINFO); 
return(ulRc); 


/■k-k-k-k-k'k-k-k-k^k'k-k-k'k'k^-k-k-k-k-k-k-k-k-k'k'k'k'k'k*'k'kir'k'k'k'k-k'k'k**'k'k'k'k'k'k'k'k^:'k'k j 

I* Queries the current track of a multiple track file */ 

^ic-k-ki^'k'k-k-k-k-k'k'k-k-k-k'k-k'k-k-k-k'k'k-k'k-k'k-k-k-k-k-k-k-k-k'k'k-k'k'k'k-k'k-k-k-k-k'k-k-kic'k'k^ 

ULONG QueryCurrentTrack ( HMMIO hmmio, PLONG plTrackNum ) 

{ 

ULONG ulRc; 

MMEXTENDINFO mmextendinfo; 

memset((PVOID)&mmextendinfo,’\0’ , sizeof(MMEXTENDINFO)); 
mmextendinfo.ulStructLen = sizeof(MMEXTENDINFO); 
mmextendinfo.ulFIags = MMIO_TRACK; 


Figure 4-19. Querying and Setting the Current Track Sample 
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ill Rc = mmi oSet( hmmi o,&mmextendi nfo,MMI0_QUERY_EXTENDEDINF0_BASE); 

*plTrackNum = mmextendinfo.ulTrackID; 
return(ulRc); 


Figure 4-19. Querying and Setting the Current Track Sample (Continued) 

The following code sample shows how to use the MMIO header APIs in con¬ 
junction with the mmioSet API to access all of the headers of a movie file. This 
sample will also be used as part of the multi-track read sample that appears 
later in this section. 


/****************************************** *******************/ 

/* Retrieve the file header, the first audio and video track */ 

/* headers from a Movie file */ 

/■k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k'k-k'k-k'k'k-k**-k-k'k-k-k-k-k-k'k-k-k'k-k-k-k'k-k'k-k-k-krk'k'k-k*-k'k'k/ 

ULONG GetMovieFi1eHeaders ( HMMIO hmmio, PMMMOVIEHEADER *ppMovieHdr, 

PMMVIDEOHEADER *ppVideoHdr, 
PMMAUDIOHEADER *ppAudioHdr, 

PULONG pulVideoTrackID, 

PULONG pulAudioTrackID ) 


ULONG 

MMIOINFO 

LONG 

PCHAR 

LONG 

PMMTRACKINFO 
ULONG 
i nt 


ul Rc = 0 ; 
mmioinfo; 

1 Len = 0; 
pBuffer = 0; 

1BytesRead = 0; 
patrackList; 
ulNumTracks; 
i ; 


*ppMovieHdr = 0; /* Initialize in case of error */ 

*ppAudioHdr = 0; /* Initialize in case of error */ 

*ppVideoHdr = 0; /* Initialize in case of error */ 

/* Check if the file was opened with data translation on */ 

ulRc = mmioGetData(hmmio, &mmioinfo, 0); 
if (ul Rc) { 

/* error */ 

printf(“Error, mmioGetData failed.\n”); 
goto GMH_end; 

} 


if (!(mmioinfo.ulTranslate & MMI0_TRANSLATEHEADER)) { 


Figure 4-20. Retrieving Track Headers Sample 
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/* error */ 

printf(“Error, File was not opened with header translation.\n”); 
goto GMH_end; 


/* Reset the current track, so that we get the file movie header */ 
ulRc = SetCurrentTrack(hmmio, MMIO_RESETTRACKS); 
if (ulRc) { 

/* error */ 

printf(“Error, SetCurrentTrack(MMIO_RESETTRACKS) fai1ed.\n”); 
goto GMH_end; 

} 


/* Query the length of the file header.it could be variable length */ 
ulRc = mmioQueryHeaderLength(hmmio, &lLen, 0,0); 
if (ulRc) { 

/* error */ 

printf(“Error, mmioQueryHeaderLength failed.\n”); 
goto GMH_end; 

} 


/* Allocate size of header */ 
pBuffer = (PCHAR) malloc (1 Len); 

*ppMovieHdr = (PMMMOVIEHEADER) pBuffer; /* return ptr to caller */ 
/* Get the movie header */ 

ulRc = mmioGetHeader(hmmio, pBuffer, lLen, &!BytesRead, 0,0); 

/* Check for error */ 
if (ulRc) { 

/* error */ 

printf(“Error, mmioGetHeader failed.\n”); 
goto GMH_end; 

} 


/* Assume there is one video track in this file, search for the */ 
/* first video track. Set the current track to this track. Then */ 
/* Query the length of the video track header */ 

patrackList = (*ppMovieHdr)->pmmTrackInfoList; 
ulNumTracks = (*ppMovieHdr)->ulNumEntries; 
if (ulNumTracks == 0) { 

/* Error */ 
goto GMH_end; 

1 


/* Search for the first video track, and the first audio track */ 
for (i =0; i < ulNumTracks; i++) { 

/* Check for the first video track */ 

Figure 4-20. Retrieving Track Headers Sample (Continued) 
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if (!(*ppVideoHdr) && 

(patrackList[i].ulMediaType == MM 10_M ED IATY P E_DIGITALVIDEO)) { 

/* Set the video track ID */ 
if (pulVideoTrackID) { 

*pulVideoTrackID = patrackList[i].ulTrackID; 

} 


/* Set the current track to this track to get its headers */ 
ulRc = SetCurrentTrack(hmmio, patrackList[i].ulTrackID); 
if (ulRc) { 

/* error */ 

printf(“Error, SetCurrentTrack(Video Track) failed.\n M ); 
goto GMH_end; 


/* Allocate video header */ 

pBuffer = (PCHAR) malloc (sizeof(MMVIDEOHEADER)); 

*ppVideoHdr = (PMMVIDEOHEADER)pBuffer; /^return ptr to caller */ 

ulRc = mmioGetHeader(hmmio,(PVOID)*ppVideoHdr, 

sizeof(MMVIDEOHEADER),&1Bytes Read, 0,0); 

if (ulRc) { 

/* error */ 

printf(“Error, mmioGetHeader(Video Track) failed.\n”); 


/* Check for the first audio track */ 
else if (!(*ppVideoHdr) && 

(patrackList[i].ulMediaType == MMI0_MEDIATYPE_AUD10)) { 

/* Set the audio track ID */ 
if (pulAudioTrackID) { 

*pulAudioTrackID = patrackList[i].ulTrackID; 


/* Set the current track to this track to get its headers */ 
ulRc = SetCurrentTrack(hmmio, patrackList[i].ulTrackID); 
if (ulRc) { 

/* error */ 

printf(“Error, SetCurrentTrack(Audio Track) failed.\n”); 
goto GMH_end; 

} 

/* Allocate audio header */ 

pBuffer = (PCHAR) malloc (sizeof(MMAUDIOHEADER)); 

*ppAudioHdr = (PMMAUDIOHEADER)pBuffer; /^return ptr to caller*/ 


Figure 4-20. Retrieving Track Headers Sample (Continued) 
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ulRc = mmioGetHeader(hmmio, (PVOID)*ppAudioHdr, 

sizeof(MMAUDIOHEADER),&1Bytes Read,0,0); 

if (ulRc) { 

/* error */ 

printf(“Error, mmioGetHeader(Audio Track) failed.\n”); 


GMH_end: 

return(ulRc); 

} 


I •■k^c'k'k'k'k'kir'k'k'k'k-k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k-k'k'k'k'k'k'k'k'k'kick'k'k j 

/* Deallocate the headers returned from a GetMovieFi1eHeaders*/ 

/* function cal 1. */ 

J'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k J 

ULONG CleanupMovieHeaders ( PMMMOVIEHEADER pMovieHdr, 

PMMVIDEOHEADER pVideoHdr, 
PMMAUDIOHEADER pAudioHdr ) 

{ 

if (pMovieHdr) 

free((PV0ID)pMovieHdr); 

if (pVideoHdr) 

free((PV0ID)pVideoHdr); 

if (pAudioHdr) 

free((PV0ID)pAudioHdr); 


j -k-k-k'k-k-k'k-k-k-k-k'k-k-k-k-k-k'k'k-k-k-k'k'k pp g -j p ■kjc-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k'k'k'k'k-k-k j 


INT main( VOID ) 


ULONG 

MMI0INF0 

HMMIO 

PMMMOVIEHEADER 
PMMAUDIOHEADER 
PMMVIDEOHEADER 
system!“cls”); 
printf(“\n\n”); 
printf (“ START: 


ul Rc = 0; 
mmioinfo; 
hmmio = 0; 
pMovieHdr = 0 
pAudioHdr = 0 
pVideoHdr = 0 


Retrieve the track headers from a Movie file Sample\n\n”) 


/* Open the file and read the headers */ 


/* Open the file with header translation */ 
memset(&mmioinfo, *\0’, sizeof(MMIOINFO)); 


Figure 4-20. Retrieving Track Headers Sample (Continued) 
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mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER; 
mmioinfo.fccIOProc = mmioF0URCC(‘A’,’V’,* I*,’ ‘); 
hmmio = mmioOpen( “e: Wmmos2\\moviesWmacaw. avi ”, &mmioinfo, 
MMIO_READWRITE); 

/* Check for error */ 
if (!hmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 


/* Get the movie headers */ 

ulRc = GetMovieFileHeaders(hmmio,&pMovieHdr,&pVideoHdr, 

&pAudioHdr,0,0); 

if (ulRc || IpVideoHdr) { /* error or no video hdr */ 

/* error */ 

printf(“Error, GetMovieFi1eHeaders failed.\n”); 
goto end; 


end: 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

CleanupMovieHeaders(pMovieHdr, pVideoHdr, pAudioHdr); 

printf (“ END: Retrieve the track headers from a Movie file Sample\n\n”); 

return( ulRc); 

} /* End of main */ 


Figure 4-20. Retrieving Track Headers Sample (Continued) 

Multi-Track Messages: 

For accessing multiple tracks of data at a time from a file, the following mes¬ 
sages are defined and supported by I/O procedures that have multiple track file 
formats: 

MMIOM_MULTITRACKREAD This message requests that data should be 

read from one or more tracks from a multi¬ 
ple track file. 

MMIOM_MULlTlK4CKWRllE This message requests that data for one or 

more tracks should be written to a multiple 
track file. The data for the tracks will be 
interleaved by the I/O procedure. 
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Multi-track Read Operations 

Movie I/O procedures must provide the MMIOMJMULTITRACKRE AD, or 
MTR message as an interface to read audio and video data from a movie file. 
(A movie contains both audio and video data.) This interface is used by the 
MMPM/2 applets and other subsystems within MMPM/2 to read movie data. 
Movie I/O procedures, however, can support the mmioRead API and the corre¬ 
sponding MMIOM_READ message to read data from the file, but this capabil¬ 
ity is not required for MMPM/2 to operate properly. 

One purpose of having a MMIOM_MULTITRACKREAD message is the 
ability to read data from a file into a large buffer (128KB). This read can be 
done as many small reads or one large read. This read is done directly into the 
applications buffer. The I/O procedure then parses the data into tracks and 
returns pointer into this buffer of individual pieces of each track. The 
MMMULTITRACKREAD data structure facilitates this reading and parsing 
by providing a track list and a record list for each track. The I/O procedure fills 
in the record list with a pointer to each record. A record is a contiguous buffer 
containing data of the same media type from one track. The records cannot 
span buffers. The I/O procedure manages this. The MTR message is ideal of 
files that have data from multiple tracks interleaved. 

The process of multi-track reads is as follows: the application supplies an 
empty buffer through the MTR message. The size is passed in the ulLength 
field of the MMMULTITRACKREAD data structure and the buffer pointer is 
passed in the pBuffer field. The I/O procedure processes the data by reading 
ulLength bytes of data into the buffer, and then parsing the data in the buffer 
by media type (e.g., audio or video) into individual records of data. Each record 
pointer is returned as an entry in the RECORDTAB array passed on the 
MTR call. 

There are two modes that the MTR can operate in, normal mode and extend¬ 
ed mode. Normal mode is the default. Extended mode is indicated by setting 
the MULTITRACKREADJEXTENDED flag in the ulFlags field of the 
MMMULTITRACKREAD data structure. Extended mode allows smaller 
amounts of data to be read at one time while allowing records (e.g., video 
frames) to be greater than the length of the small read ( ulLength field). Movie 
I/O procedures are not required to support the extended mode, but supporting 
it will improve the presentation of the movie. Refer to the discussion of SCSI 
vs. IDE hard drives in the MMPM/2 Tips and Techniques chapter. 

In normal mode, the pBuffer field always points to the beginning of the 
buffer and ulLength indicates the number of bytes to be read into the buffer. 
The buffer is filled completely with each call to MTR and the entire buffer and 
all records within this buffer are returned to the application. Subsequent calls 
to MTR, read ulLength bytes of data into the buffer starting at the point that 
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the last call finished. Any records that span two buffers will be returned on the 
MTR that processes the second buffer. 

In extended mode, the pBuffer field points to the beginning of the buffer on 
the first call to MTR and ulLength indicates the number of bytes to be read 
into the buffer. With each call to MTR, the ulBufferLength field, the actual 
total buffer length, is reduced by ulLength bytes, and pBuffer points to the cur¬ 
rent location in the buffer. On subsequent calls to MTR, ulLength bytes of data 
are read into the buffer starting at pBuffer. The application must continue to 
make MTR calls with the same large buffer until a ulBufferLength of 0 is 
reached. The application can then proceed to process the data in the buffer. 

Multi-track Read Data Structures 



Figure 4-21. Multi-track Read Data Structures 

The MMMULTITRACKREAD data structure contains the pointer to the 
read buffer ( pBuffer ), the length of the read buffer for this read call ( ulLength ), 
and the actual buffer length of the entire read buffer for extended mode reads 
0 ulBufferLength ). It also contains the number of tracks to read (. ulNumTracks ). 
This can be a subset of the tracks in the file. The MMMULTITRACKREAD 
structure also contains a pointer to an array of another data structure, 
TRACKMAP, that contains the list of tracks to read from and information 
about each track. In addition, the MMMULTITRACKREAD structure also 
contains a ulFlags field to indicate extended mode. The ulFlags field is also 
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used by MTR to returns not done (MULTITRACKREAD_NOTDONE) and 
end-of-file (MULTITRACKREADJEOF) conditions. The not done condition 
indicates that number of record entries in the RECORDTAB array was not 
large enough. The application should issue the MTR again with the same 
pBuffer to get the rest of the record entries. The end-of-file condition indicates 
the end of file has been reached. 

The TRACKMAP array contains information about each track, like the 
media type of the track ( ulMediaType ), the track Id number ( ulTrackID ), which 
identifies the track to the I/O procedure. It also indicates the number of record 
entries for this track being passed to the I/O procedure ( ulNumEntries ), and a 
pointer to an empty array of records (RECORDTAB) data structure. The 
RECORDTAB data structure contains the pointer to an actual data record, 
the length and other additional information about the individual record itself. 
The RECORDTAB array is filled in on the read by the I/O procedure. 

The following code sample shows how to use the MMIOMJMULTITRACK- 
READ message to extract the audio data from a movie file. The 
GetMovieFileHeaders routine from the previous sample is used for this 
sample. 


/*********** ****** ******** * -kick ** ** ** ******* ****** **** ******** ** J 

I* Extract the audio track from a movie file and save to audio file */ 
/************************************* ********* **********************/ 
#define NUM_RECORDS 5 


ULONG 

ul Rc = 0; 

ULONG 

ulErrorRet = 0; 

LONG 

1 Rc; 

MMIOINFO 

mmioinfo; 

HMMIO 

hmmioFrom = 0; 

HMMIO 

hmmioTo = 0; 

PMMMOVIEHEADER 

pMovieHdr = 0; 

PMMAUDIOHEADER 

pAudioHdr = 0; 

PMMVIDEOHEADER 

pVideoHdr = 0; 

PCHAR 

pBuffer = 0; 

ULONG 

ulLength; 

ULONG 

ulAudioTrackID; 

LONG 

1NumBytesRead = 0; 

MMMULTITRACKREAD 

mtread; 

TRACKMAP 

trackmap; 

RECORDTAB 

recordtab[NUM_REC0RDS] 

i nt 

i ; 

BOOL 

fEOF = FALSE; 


Figure 4-22. Multi-track Read Sample 
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system(“cls”); 
printf(“\n\n”); 

printf (“ START: Extract the audio track from a movie file and save to 
audio file Sample\n\n”); 


/* Open the file and read the header for the information needed */ 
/* to extract audio and save it to wave file */ 

/* Open the file with header translation */ 

memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 
mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER; 
mmioinfo.fccIOProc = mmioF0URCC(‘A’,’V’,’I *,’ *); 
hmmi oFrom = mmi oOpen (“e: Wmmos2\\movi esWmacaw. avi ” ,&mmioi nfo, 
MMI0_READ); 

/* Check for error */ 
if (!hmmioFrom) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 


/* Get the movie headers */ 

ulRc = GetMovi eFi1eHeaders(hmmioFrom,&pMovieHdr,&pVideoHdr, 

&pAudioHdr,0,&ulAudioTrackID); 
if (ulRc || IpAudioHdr) { /* error or no audio hdr */ 

/* error */ 

printf(“Error, GetMovieFi1eHeaders failed.\n”); 
goto end; 


/* Create the TO file with header translation */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 

mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER+MMIO_TRANSLATEDATA; 

mmioinfo.au!Info[3] = MMIO_MEDIATYPE_AUDIO; 

mmioinfo.fccIOProc = mmioFOURCCC‘W’,* A’,’V *,’E*) ; 

hmmioTo = mmioOpen(“macaw.wav”, &mmioinfo, MMIO_CREATE+MMIO_WRITE); 

/* Check for error */ 

if (!hmmioTo) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 

} 


/* Set the audio header for the TO file */ 
ulRc = mmioSetHeader(hmmioTo,pAudioHdr,sizeof(MMAUDIOHEADER), 
&1NumBytesRead, 0,0); 

/* Check for error */ 

Figure 4-22. Multi-track Read Sample (Continued) 
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if (ulRc) { 

/* error */ 

printf(“Error, mmioSetHeader failed.\n”); 
ulRc = mmioGetLastError(hmmioTo); 
printf(“Error , %1d\n”,ulRc); 
goto end; 


/* Allocate the read buffer */ 
ulLength = 32*1024; /* 32KB */ 

pBuffer = (PCHAR) malloc (ulLength); 

/* Initialize the MTR data structures */ 
mtread.ulLength = ulLength; 
mtread.pBuffer = pBuffer; 

mtread.ulNumTracks = 1; /* Only want audio track */ 

mtread.pTrackMapList = &trackmap; 

mtread.ulBufferLength = 0; /* unused, not extended mode */ 

mtread.ulReserved = 0; /* unused */ 

trackmap.ulTrackID = ulAudioTrackID; 
trackmap.pRecordTabList = recordtab; 

/* get audio from the movie file and write it to an audio file */ 
/* until there is no more data in the movie file */ 

while (!fEOF) { 

mtread.ulFIags = 0; /* normal mode */ 

trackmap.ulNumEntries = NUM_REC0RDS; 

/* Do MTR */ 

ulRc = mmioSendMessage(hmmioFrom,MMIOM_MULTITRACKREAD, 

(LONG)&mtread,sizeof(mtread)); 

if (ulRc) { 

if ((ulRc == MMI0_ERR0R) && 

(ulErrorRet = mmioGetLastError(hmmioFrom))) { 

/* error */ 

ulRc = ulErrorRet; 

goto end; 

} 

if (ulRc == MM 10 E RR_E0 F_S E EN) { /* Check for EOF */ 

fEOF = TRUE; 
ulRc = N0_ERR0R; 


el se { 

fEOF = (mtread.ulFIags & MULTITRACKREAD_EOF); /* Set EOF */ 

} 


Figure 4-22. Multi-track Read Sample (Continued) 
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/* Don’t need to worry about the not done case, because we */ 
/* always pass the same buffer to the I/O procedure. If we */ 
/* had several buffers that we were using, we would need to */ 
/* handle the not done case. You will see the # records */ 
/* alternate between 5 and 2, this is the not done condition */ 
/* In other words, There are 7 records of audio in each 32KB */ 
/* of the movie file */ 


/* Write out each record returned from the MTR message */ 
for (i=0; i < trackmap.ulNumEntries; i++) { 

1Rc = mmioWrite(hmmioTo,recordtab[i].pRecord, 
recordtab[i].ulLength); 


end: 

if (pBuffer) 

free((PVOID)pBuffer); 

if (hmmioFrom) 

ulRc = mmioClose(hmmioFrom,0); 
if (hmmioTo) 

ulRc = mmioClose(hmmioTo,0); 

CleanupMovieHeaders(pMovieHdr, pVideoHdr, pAudioHdr); 

printf (“ END: Extract the audio track from a movie file and save to audio 
fi1e Sample\n\n”); 


Figure 4-22. Multi-track Read Sample (Continued) 

Multi-track Write Operations 

Movie I/O procedures must provide the MMIOM_MULTITRACKWRITE , or 
MTW, message as an interface to write audio and video data to a movie file. 
This interface is used by the applications and other subsystems within 
MMPM/2 to write movie data. Movie I/O procedures are not required to sup¬ 
port the mmioWrite API or the MMIOM_WRITE message. The purpose of 
having a MMIOM_MULTITRACKWRITE message is to give the application 
control to interleave the different tracks of information. On a MTW message, 
the application passes the MMMULTITRACKWRITE data structure to the 
multiple track I/O procedure. 
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Multi-track Write Data Structures 


Audio RECORDTABWRITE 


MMMULTITRACKWRITE 



pRecord 

ulLength 

ulParml 

ulParm2 


pRecord 

ulLength 

ulParml 

ulParm2 


_^^udio data buffers 

^ audio 
data 


audio 

data 


video data buffers 



Video RECORDTABWRITE 


Figure 4-23. Multi-track Write Data Structures 

The MMMULTITRACKWRITE data structure contains the number of 
tracks to write ( ulNumTracks ). It also contains a pointer to an array of another 
data structure (TRACKMAP) that contains the list of tracks to write to and 
information about each track ( pTrackMapList ). In addition, a ulFlags field is 
defined, and currently one flag is defined, MULTITRACKWRITE _MERGE. 

If the MULTITRACKWRITE_MERGE bit flag is set, MTW attempts to 
interleave the individual tracks (for example, in the case of movies, digital 
video track with the digital audio track). Interleaving is accomplished based on 
the size of the audio buffer. For example, if a 4K audio buffer represents one- 
third of a second and a frame rate is 15 frames per second, the interleave factor 
would be 5:1 (5 video frames to 1 audio chunk). There is no attempt to break 
the audio buffers into smaller buffers and interleave the data at a one-to-one 
rate. This could be done as a post-process if required. The MTW message can 
be used to interleave the tracks at a one-to-one rate if requested. Refer to the 
AVI file utility that ships as part of the Video IN product, this utility will per¬ 
form these types of functions. If the MULTITRACKWRITE_MERGE bit flag 
is NOT set, MTW writes all of the records sequentially from the first track 
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(first entry in the TRACKMAP array). Next, MTW writes all records for the 
second track. This method allows the application to control the interleaving 
rate and how the data is written to the file. 

The TRACKMAP array contains information about each track, like the 
media type of the track ( ulMediaType ), the track ID number ( ulTrackID ), 
which identifies the track to the I/O procedure. It also indicates the number of 
record entries for this track being passed to the I/O procedure ( ulNumEntries ), 
and a pointer to an array of records (RECORDTABWRITE) data structure. 
The RECORDTABWRITE data structure contains the pointer to an actual 
data record, the length and other additional information about the individual 
record itself. The RECORDTABWRITE array is filled in by the application 
and processed by the I/O procedure. 

The MTR and MTW messages can be very useful for an application that 
would like to perform a frame-step recording or a file to file conversion. In the 
case of a file to file conversion, the MTR message would be used to read the 
data from the source file, which would then be decompressed from the source 
format. The data could then be recompressed in the target format and written 
to the file using the MTW message. Refer to the CODEC Access Messages sec¬ 
tion of this chapter for details on compressing and decompressing data. 

Video Frame Specific RECORDTAB Flags 

Both the MMIOM_MULTITRACKREAD and MMIOMJMULTITRACK- 
WRITE messages deal with records (RECORDTAB entry) of data. These 
records belong to a track of a multi-track file. Each track contains data of one 
media type. For tracks that contain video data, each record typically will repre¬ 
sent one video frame of data. This is not always the case, as in the MPEG video 
track. An MPEG video frame may be spread across several records and the 
video frames are not sequential like other video formats. 

Each record (RECORDTAB entry) has two fields that contain additional 
information about each video frame. On a MMIOM_MULTITRACKREAD 
call, these two fields are filled in by the I/O procedure based on information in 
the movie file. These fields in the RECORDTAB entry are then passed with 
the video frame to the I/O procedure CODEC access message 
MMIOM_DECOMPRESS when the video frame is decompressed. 

ulParml field: This field has data record specific data. This field can 
return one of the following flags on a MMIOMJMULTITRACKREAD 
message: 

MMIO_IS_KEY_FRAME: The data record contains a key or refer¬ 
ence video frame. 
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MMIO_ISJPALETTE: The data record contains a video palette. 
This data record is not considered a video frame. 

MMIO_INVI8IBLE_FRAME: The data record contains a video 
frame that should not be displayed. This flag is part of the seek sup¬ 
port for movies. It allows a movie to be “seeked” to a delta frame (non¬ 
key frame). This frame needs to be decoded, but should not be dis¬ 
played. 

MMIO_NULL_FRAME: The data record contains a video frame of 
zero length. Some file formats contain these zero length video frames, 
or null frames, as filler for frames missed during capture of the movie, 
especially during real-time capture. 

ulParm2 field: This field has data record specific data. This field is used 
to return the video frame number for this video frame if this track is a 
video track. 

On a MMIOM_MULTITRACKWRITE call, these two fields are filled in by 
the I/O procedure CODEC access message MMIOM_COMPRESS when the 
video frame is compressed. These fields in the RECORDTABWRITE entry 
are then passed with the video frame to the I/O procedure on the 

MMIOM.MULTITRACKWRITE message: 

ulParml field: This field has data record specific data. This field can con¬ 
tain one of the following flags on a MMIOM_MULTITRACKWRITE 
message: 

MMIO_IS_KEY_FRAME: The data record contains a key or refer¬ 
ence video frame. 

MMXO_XS_PALETTE : The data record contains a video palette. 
This data record is not considered a video frame. 

ulParm2 field: This field has data record specific data. On a 
MMIOM_MULTITRACKWRITE message, this field must contain the 
number of NULL frames that should be inserted before this frame. This is 
used during real-time capture of video to save the number of missed 
(NULL) frames so that the video stream will playback at the correct rate. 

Reading and Writing from a File 

For accessing data in files that are not multiple track in nature, the 
mmioRead and mmioWrite APIs can be used. Use the mmioRead and 
mmioWrite APIs to read and write to files opened by mmioOpen. The MMIO 
manager maps these APIs to MMIOM_READ and MMXOM_WRITE mes- 
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sages that are sent to an I/O procedure. The application must pass a buffer and 
length on all read or write calls. These calls will return the number of bytes 
transferred. 

To determine whether an I/O procedure supports these APIs and messages, 
the mmioGetFormats API should be used to query the capability flags for the 
I/O procedure. The mmioGetF ormats will return an MMFORMATINFO 
data structure that contains a ulFlags field. This field will have a subset of the 
following flags set if the I/O procedure supports read and write: 


MMIO_CANREADTRANSLATED 

MMIO_CANWRITETRANSLATED 

MMICLCANREADWRITETRANSLATED 

MM 10_CAN READUNTRANSLATED 

MMIO_CANWRITEUNTRANSLATED 

MMIO_CANREADWRITEUNTRANSLATED 


These flags will also indicate whether the I/O procedure can handle translat¬ 
ed and/or untranslated data access. Refer to the Data Translation section for a 
detailed look at translated vs. untranslated. 

Seeking Operations 

The MMIO subsystem provides two services to seek to a position within a file: 
the mmioSeek API and the MMIOM_SEEKBYTIME message. The seek API 
and message can be used to change the current file position. The current posi¬ 
tion, or current file pointer, points to the place in the file where the next read 
or write operation will take place from. 

With regard to quality of service, seek operations should not be performed 
while QOS is enabled. This causes adverse affects on performance because of 
the read-ahead performed by the network server. Refer to the Quality of 
Service Network Storage System section of this chapter for more details. 

Seeking APIs and Messages: 

mmioSeek This API requests that the file position be 

moved. The file position must be expressed as a 
byte position within a file. This maps to a 
MMIOM_SEEK message to the I/O procedure. 
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MMIOM_SEEKBYTIME This message requests that the file position 

should be moved. The file position must be 
expressed in units of time, not by the byte posi¬ 
tion within a file. 

There are two parameters for the seek operations. The lOffset parameter 
specifies an offset to move the file position to. The lOrigin parameter specifies 
how the offset is interpreted, or the type of seek. Three types of seek requests 
that can be made on these seek operations are: 

SEEKJ3ET This indicates that an absolute seek should be per¬ 

formed, interpreting the lOffset parameter to be an offset 
from the beginning of the file. 

SEEK_CUR This indicates that a relative seek should be performed, 

interpreting the lOffset parameter to be an offset from 
the current position. The lOffset can be negative or posi¬ 
tive to indicate the direction of the seek. 

SEEK_END This indicates that a relative seek from the end of the 

file should be performed. The lOffset parameter indicates 
the offset from the end of file. The lOffset can be negative 
or positive to indicate the direction of the seek. 

Seeking past end of file, seeks to a new position past the end of file; it is not 
an error condition. These seek operations can also be used to query the current 
position of the file pointer. This can be done by specifying the SEEK_CUR flag 
in the lOrigin parameter and indicating an lOffset of 0. This will seek to the 
current position plus 0. 

Time vs. Byte Seeking 

Currently, some I/O procedures support either the byte-oriented seek API or 
the time-oriented seek message. Some types of data do not support byte-orient¬ 
ed seeks because there is no direct conversion between time and the byte posi¬ 
tion within a file. For example, video data is typically organized into video 
frames, where each video frame is a small self-contained data item for one 
video frame. It would not make sense to seek into the middle of a video frame. 
Therefore, a time-oriented seek would be used in this instance. Files that con¬ 
tain spatially compressed audio data, or MIDI files support the time-oriented 
seek, but not the byte-oriented seek. The MMIOM_SEEKBYTIME message 
always expects time values to be represented in MMTIME units, or 1/3000 of a 
second. 

For some types of data, doing a conversion between the byte position and a 
time position is possible. It this case, either seek interface could be used to seek 
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the file. In other cases, it is not possible to convert a byte position to a time posi¬ 
tion or vice versa. For this type of data, the appropriate interface should be used. 
To do a time to byte conversion for PCM audio, the standard presentation audio 
header should be queried for the file. The number of bits per sample, sample size, 
and the number of samples per second should be retrieved from the header and 
used to calculate, from the time position, a byte position to seek to. 

In general, if an application needs to use the MMIO seek operations directly 
instead of the MCI device seek operations, then it will need to know the media 
type of the data with which it is dealing. This will allow the application to 
make the correct choice on which seek interface to use. Remember, an I/O pro¬ 
cedure may not support both types of seeks. 

Translated vs. Untranslated Seeking 

Some I/O procedure support the concept of translated data access. In these 
cases, it is desirable to be able to seek the file in translated mode as well. This 
allows the application to be data format independent, since an untranslated 
seek would only be valid in relation to untranslated data access. Otherwise, 
the application would need to understand the untranslated data format to be 
able to request a seek request correctly. 

Multiple Track File Seeking 

For files that contain multiple tracks of data, the current track can be set to 
perform a seek on an individual track. Check the MMFORMATINFO capabil¬ 
ities flags returned by mmioGetFormats to determine whether this function 
is available for a given multiple track file format. The current track must be 
set to MMIO_RESETTRACKS for file seeks to be performed instead of a 
track seek. 

The mmioSet API 

The mmioSet API is a general purpose interface to an I/O procedure that is 
used to query and set information relative to an open data element or file. 
Currently, movie file format I/O procedures are required to support this mes¬ 
sage. It provides three sets of services: 

1. It can query and set the current track of a multiple track file. This is dis¬ 
cussed in detail in the Dealing with Multiple Track Files section of this 
chapter. 

2. It can set the current read mode used by an I/O procedure during 

MMIOM.MULTITRACKREAD requests. 
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3. It can query and associate a CODEC procedure to a data track within a 
movie file. This allows an application to either change the default CODEC 
that was associated when a movie was loaded, or it is used to associate a 
CODEC with a track of a newly created file. 

Setting the Read Mode 

Three read modes are available: MMXO_NORMAL_READ, 
MMXO_8CAN_READ, and MMXO_REVERSE_READ. MMIO_NORMAL_ 
READ is the default mode for reading data from an I/O procedure. This mode 
directs the I/O procedure to return all data for a track and to not filter any 
data out. In the case of a video track, the MMIO_SCAN_READ mode directs 
the I/O procedure to filter out some of the video frames and only return the 
Intracoded frames (I-frames) or Key frames for a movie. This mode allows the 
video track to be scanned and displayed quickly for movies that have I-Frames 
at regular intervals within the video track. Some movie files may have one I- 
Frame at the beginning of the movie, in these cases, only the first video frame 
will be returned. This mode is invalid for audio tracks. 

The MMIO_REVERSE_READ mode directs the reading operation to 
return the data in the track in reverse order. This operates in the same way as 
the MMXO_SCAN_READ mode, except in reverse. Only I-Frames are 
returned when in this mode. The MMIO_REVERSE_READ and 
MMXO_SCAN_READ are optional and may not be supported by some movie 
file formats. The following sample shows how to set the read mode for a file. 


ULONG SetMode ( HMMIO hmmio ) 

{ 

ULONG ulRc; 

MMEXTENDINFO mmextendinfo; 

memset((PVOID)&mmextendinfo,’\0’ , sizeof(MMEXTENDINFO)); 
mmextendinfo.ulStructLen = sizeof(MMEXTENDINFO); 

/* mmextendinfo.ulFIags = MMIO_NORMAL_READ; */ 

/* mmextendinfo.ulFIags = MMIO_SCAN_READ; */ 
mmextendinfo.ulFIags = MMIO_REVERSE_READ; 

ulRc = mmioSet(hmmio,&mmextendinfo,MMIO_SET_EXTENDEDINFO); 
return(ulRc); 


Figure 4-24. Setting the Read Mode Sample 



Associating a CODEC with a File Format I/O Procedure 
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The mmioSet API can be used to associate a CODEC with a video track in a 
movie track. This indicates the CODEC to be used to decompress or compress 
the data for the file. The mmioSet API can also be used to query the currently 
loaded CODEC for a given track within a movie file. In the pre-OS/2 Warp ver¬ 
sions of MMPM/2, the AVI movie PO procedure allows only one CODEC to be 
associated with a movie file. This CODEC must be a video CODEC. In the 
OS/2 Warp version of MMPM/2, the AVI movie I/O procedure supports query¬ 
ing and associating a CODEC to a specific track. This allows multiple CODECs 
to be associated with the same movie file. This is useful for playing movies that 
contain compressed audio in the audio track. An audio CODEC can be associat¬ 
ed with the audio track to decompress the audio on playback of the movie. 
When querying or associating a CODEC, set the current track to the appropri¬ 
ate track to access. This can be done on the same mmioSet call as the associ¬ 
ate, as in the sample following. If the current track is MMIO_RESET- 
TRACKS, then track 0 is used as the current track. The mmioSet API will 
only query the CODEC for one track; there is no way to query all CODECs for 
a file on one mmioSet call. 

When associating a CODEC, the CODECASSOC structure can be used to 
associate a CODEC when creating a new file (for recording). Usually, when a 
file is opened for reading, if it is a movie with a compressed video, the video 
decompressor will automatically be loaded by the I/O procedure, so no associa¬ 
tion of a CODEC is needed by the application. However, for file format conver¬ 
sions, it is necessary to possibly load a different decompressor for the conver¬ 
sion. For example, the display may be set to an 8-bit color mode, but the file 
data is stored in a 16-bit data form. In the case of file conversions, it would be 
best to use the 16-bit decompressor instead of the 8-bit decompressor. By re¬ 
associating the 16-bit decompressor, the 8-bit decompressor is unloaded, and 
the other is loaded. 

Note that associating a CODEC on an existing file will overwrite the exist¬ 
ing CODEC header information in the file with the new information, whether 
data is written to the file or not. This will happen if the file is opened in 
MMIO.READWRITE or MMIO_WRITE mode. 

The following sample shows how an application can associate a CODEC 
with a video track of an open file. This can be useful during movie file to movie 
file conversion. This sample associates a decompressor. The AssociateCodec 
routine could also be used to associate a compressor with a newly created file 
to indicate the CODEC to use when recording compressing video data for a 
new movie file. 
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/**************************** ******************************************j 


/* AssociateCodec */ 
/* input: */ 
/* HMMIO hmmio - handle to open file */ 
/* ULONG ulCompressionType - FOURCC of CODEC */ 
/* ULONG ulFlag - CODEC flags from CODECINIFILEINFO data structure*/ 
/* PVOID pControlHdr - Codec specific open info or NULL *7 
/* ULONG ulColorEncoding - src if COMPRESSing, else dst */ 
/* ULONG ulFrameDur - frame duration in MMTIME units */ 
/* ULONG ulSrcX - Source X dimension */ 
/* ULONG ulSrcY - Source Y dimension */ 
/* ULONG ulDstX - Target X dimension */ 
/* ULONG ulDstY - Target Y dimension */ 
/* ULONG ulVideoTrackID - Track ID of track to associate too */ 


I'k'k'kkk'kkkk'kkickk'k'k-kk'k'kkk-k-k'k-k-kk-k'k-k'kk-k-k'kkk-k-kkk-k-k-kk-k'kk'k-k'k-k-k'kk-k'k'kkick-k-k-k-k-k-k-k-kl 


ULONG AssociateCodec( HMM10 
ULONG 
ULONG 
PVOID 
ULONG 
ULONG 
ULONG 
ULONG 
ULONG 
ULONG 
ULONG 


hmmio, 

ulCompressionType, 

ulFIag, 

pControl Fidr, 

ulFrameDur, 

ulColorEncoding, 

ulSrcX, 

ulSrcY, 

ulDstX, 

ulDstY, 

ulVideoTrackID ) 


ULONG 

MMEXTENDINFO 

MMVIDEOOPEN 

CODECASSOC 

CODECOPEN 

CODECINIFILEINFO 

CODECVIDEOHEADER 

CODECVIDEOHEADER 


ul Rc; 

mmextendinfo; 
mmvideoopen; 
codecassoc; 
codecopen; 
c i f i ; 
cvhSrc; 
cvhDst; 


/* Setup source video header */ 

cvhSrc.ulStructLen = sizeof(CODECVIDEOHEADER); 

cvhSrc.cx = ulSrcX; 

cvhSrc.cy = ulSrcY ; 

cvhSrc.cPlanes = 1; 

cvhSrc.cBitCount = 16; /* Hardcode this field for sample */ 

cvhSrc.genpal.ulNumColors = 65536; /* Hardcode this field for sample */ 

/* Setup Destination video header */ 

cvhDst.ulStructLen = sizeof(CODECVIDEOHEADER); 

cvhDst.cx = ulDstX; 

cvhDst.cy = ulDstY;; 

Figure 4-25. CODEC Associate Sample 
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cvhDst.cPlanes = 1; 

cvhDst.cBitCount = 16; /* Hardcode this field for sample */ 

cvhDst.genpal.ulNumColors = 65536; /* Hardcode this field for sample */ 

/* Setup the CODEC open structure */ 

memset((PVOID)&codecopen,’\0’, sizeof(CODECOPEN)); 

codecopen.pControlHdr = pControlHdr; 

codecopen.pSrcHdr = (PVOID)&cvhSrc; 

codecopen.pDstHdr = (PVOID)&cvhDst; 

/* Setup CODEC Search structure */ 

memset (( PV0ID)&ci f i , ’\0\ si zeof (CODECINI FI LEINFO)); 

cifi.ulStructLen = sizeof(CODECINIFILEINFO); 

cifi.ulCompressType = ulCompressionType; 

cifi.ulCompressSubType = OL; 

ci f i. ul CapsFl ags = ulFlag; 

cifi.ulMediaType = MM 10_M EDIATY P E_DIGITALVIDEO; 

/* Set the COMPRESS only stuff */ 
if (ulFlag & CODEC.COMPRESS) { 

cvhSrc.ulColorEncoding = ulColorEncoding; 
cvhDst.ulColorEncoding = MMIO_COMPRESSED; 

/* If RAW, unset C0DEC_C0MPRESS flag */ 
if (ulCompressionType == MCI_VID_COMP_NONE) 
ulFlag &= ~C0DEC_C0MPRESS; 

mmvideoopen.ulStructLen = sizeof(MMVIDEOOPEN); 

mmvideoopen.ulKeyFrameRate = -1;/*Hardcode this field for sample*/ 
mmvideoopen.ulSeale = 1000000; 
mmvideoopen.ulRate = 

(UL0NGM(1000000.0*1000000.0/ulFrameDur)+0.5); 


/* Application Should check the CODECINIFILEINFO data structure */ 
/* for this CODEC to see if the C0DEC_DATA_C0NSTRAINT or */ 
/* C0DEC_SET_QUALITY flag is set. If yes then the CODEC expects */ 
/* that these fields setup video open structure for C0MRESS only */ 
mmvideoopen.ulDataConstraint = -1;/* Hardcode for sample */ 
mmvideoopen.ulConstraintlnterval=-l;/* Hardcode for sample */ 
mmvideoopen.ulQuality = -1; /* Hardcode this field for sample */ 


codecopen.pOtherlnfo = (PV0ID)&mmvideoopen; /*need for COMPRESS */ 


/* Set the DECOMPRESS only stuff */ 
el se { 

cvhSrc.ulColorEncoding = MM 10_C0MP RESS ED; 
cvhDst.ulColorEncoding = ulColorEncoding; 

Figure 4-25. CODEC Associate Sample (Continued) 
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} 

cifi.ulCapsFlags = ulFlag; /* After RAW check */ 
codecopen.ulFIags = u1 Flag; 

/* Setup CODEC assocciate structure */ 
codecassoc.pCodecOpen = &codecopen; 
codecassoc.pCODECIniFi1elnfo = &cifi; 

/* Setup mmio SET structure */ 

memset((PVOID)&mmextendinfo,’\0’, sizeof(MMEXTENDINFO)); 
mmextendinfo.ulStructLen = sizeof(MMEXTENDINFO); 
mmextendinfo.ulFIags = MMI0_C0DEC_ASS0C | MMIO_TRACK; 
mmextendinfo.ulNumCODECs = 1L; /* only valid input */ 

mmextendinfo.pCODECAssoc = &codecassoc; 

mmextendinfo.ulTrackID = ulVideoTrackID; /*Assoc CODEC with track */ 
/* Call the I/O Procedure */ 

ulRc = mmioSet(hmmio,&mmextendinfo,MMIO_SET_EXTENDEDINFO); 
return(ulRc); 


/*************************************************************/ 
/* Associate a CODEC with a movie file video track */ 

/*************************************************************j 

INT main( VOID ) 


ULONG 

MMIOINFO 

HMMIO 

PMMMOVIEHEADER 
PMMAUDIOHEADER 
PMMVIDEOHEADER 
ULONG 


ul Rc = 0 ; 
mmioinfo; 
hmmio = 0; 
pMovieHdr = 0; 
pAudioHdr = 0; 
pVideoHdr = 0; 
ulVideoT rackID; 


system(“cls”); 
printf(“\n\n”); 

printf (“ START: Associate a decompressor Sample\n\n”); 


/* Open the file and read the header for the information needed to */ 
/* set the quality of service parameters */ 

/* Open the file with header translation */ 
memset(&mmioinfo, ‘\0*, sizeof(MMIOINFO)); 
mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER; 
mmioinfo.fccIOProc = mmioFOURCCC‘A’,’V’,’I*,’ *); 

Figure 4-25. CODEC Associate Sample (Continued) 
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hmmio = mmioOpen(“e:\\mmos2\\movies\\macaw.avi 
&mmioinfo,MMI0_READ); 

/* Check for error */ 
if (!hmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 


/* Get the movie headers */ 

ulRc = GetMovie Fi1eHeaders(hmmio,&pMovieHdr,&pVideoHdr,&pAudioHdr, 

&ulVideoTrackID.O); 

if (ulRc || ipVideoHdr) { /* error or no video hdr */ 

/* error */ 

printf(“Error, SetMovieFi1eHeaders failed.\n”); 
goto end; 


/* A CODEC was associated with the movie on open of the movie, but */ 
/* we want to change the output of the decompressor to a different */ 


/* color depth then we can display, so change it here. This */ 
/* will unload the current CODEC and load this one. */ 
/* In a real application, the apps should first query the CODEC */ 
/* information and then make any changes to the destination data */ 
/* structure and re-associating. */ 
ulRc = AssociateCodecChmmio, /* movie file */ 


HEX_FOURCC_ULTI, /* Pick Ultimotion CODEC */ 

CODEC_DECOMPRESS, /* Decompressor */ 
(PVOID)NULL, 

200, /* 3000/200 = 15 FPS */ 

MMI0_RGB_5_6_5, /* Color encoding */ 

320, /* src x */ 

240, /* src y */ 

320, /* dst x */ 

240, /* dst y */ 

ulVideoTrackID); /* track to assoc CODEC */ 

if (ulRc) { 

/* error */ 

if (ulRc == MMI0_ERR0R) 

ulRc = mmioGetLastError(hmmio); 
printf(“Error %d, AssociateCodec fai1ed.\n”,ulRc); 
goto end; 


/* Read data from file and call the CODEC access messages to */ 
/* decompress the video frame here */ 

end: 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

Figure 4-25. CODEC Associate Sample (Continued) 
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CleanupMovieHeaders(pMovieHdr, pVideoHdr, pAudioHdr); 

printf (“ END: Associate a decompressor Sample\n\n”); 

return( ulRc); 

} /* End of main */ 


Figure 4-25. CODEC Associate Sample (Continued) 

CODEC Access Messages 

Once a CODEC has been associated with an I/O procedure, the CODEC access 
messages can be used to call the CODEC to either compress or decompress 
data. Movie I/O procedures are required to support the following two CODEC 
access messages: 

CODEC Access Messages: 

MMIOM_COMPRESS This message is used to compress data for a 

file format. 

MMIOM_DECOMPRESS This message is used to decompress data for a 

file format. 

These messages provide access to a CODEC that was opened by the I/O pro¬ 
cedure. Typically, when a file is opened for read or read and write, the file 
headers are read into memory by the I/O procedure. The I/O procedure then 
determines if any CODECs need to be loaded for this file. If so, it loads the 
appropriate CODECs. Since the movie I/O procedures do not provide a trans¬ 
lated data access function, these messages are provided instead. These can be 
used, for example, in conjunction with the multiple track messages to provide 
the ability to translate data to a form that can be displayed. 

Editing Operations 

Some I/O procedures provide the ability to edit files. These editing operations 
are typically done through the clipboard. The usual CUT, COPY, and PASTE 
operations, as well as redo, undo functions can be supported. Currently, some 
audio and movie file formats support these messages. The Audio I/O proce¬ 
dures use byte based editing to get good granularity, but this does not work 
well for compressed forms of audio. Movie I/O procedures on the other hand, 
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perform editing operations using time units instead of byte positions within 
the data. 

Refer to the Digital Video Device Fundamentals chapter for a sample of edit¬ 
ing a movie using the MCI interface. Refer also to the Audio Playback and 
Record chapter for details on editing audio files at the MCI interface. Use of 
the MCI interface is recommended whenever possible instead of the MMIO 
interfaces for editing. Note that these messages are optional messages and are 
not supported by all I/O procedures. The best way to determine whether an I/O 
procedure supports these editing messages is to send one of them to the I/O 
procedure. If MMIOERR_UNSUPPORTED__MESSAGE is returned, the 
editing message is not supported. 


Editing and Clipboard Messages: 

MMIOM_BEGININSERT 

mmiomjbeginrecord 

MMIOM_CLEAR 

MMIOM_COPY 

MMIOM_CUT 

MMIOM_DELETE 

MMIOM_ENDINSERT 


This message requests all subsequent 
mmioWrite API calls insert data at the 
current seek position instead of overwrit¬ 
ing the data. 

This message requests all subsequent 
mmioWrite AlPI calls be considered one 
logical unit by an MMIOM_UNDO or 
MMIOM_REDO message. 

This message requests that a specified 
range be deleted from a file. The clip¬ 
board is not used for this operation. 

This message requests that a specified 
range should be copied to the clipboard. 

This message requests the specified 
range should be copied to the clipboard 
and then deleted. 

This message requests that information 
should be deleted from a file. 

This message requests that all subse¬ 
quent mmioWrite API calls overwrite 
data at the current seek position. This is 
the default mode of operation for an I/O 
procedure. 
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MMIOMJENDRECORD 

MMIOMJPASTE 

MMIOMJREDO 

MMIOM.SAVE 

MMIOM.STATUS 

MMIOMJTEMPCHANGE 

MMIOMJJNDO 

MMIOM_WINMSG 


This message indicates that the logical 
record operation has ended. 

This message requests that data from the 
clipboard be inserted into the file at the 
position specified. An optional delete 
operation can be performed on a specified 
range prior to the insertion. 

This message requests that the last logi¬ 
cal action that was undone by 

MMIOM_UNDO be redone. 

This message requests that temporary 
changes in a file should be made perma¬ 
nent. A new file name can be supplied to 
save the changes. 

This message requests status of clip¬ 
board, undo, and redo operations. 

This message requests all subsequent 
mmioWrite API calls to an I/O proce¬ 
dure for a file should be treated as tem¬ 
porary changes. The changes will not be 
saved to the file when closed by 
mmioClose unless an MMIOM_SAVE 
message is sent to the I/O procedure. 

This message requests that the last 
logical action (MMIOM_DELETE, 
MMIOM.BEGININSERT, 
MMIOM_ENDINSERT, 
MMIOMJJNDO, MMIOM_ REDO) be 
undone. 

This message allows an application to 
pass PM messages from a window proce¬ 
dure to an I/O procedure. It can be used 
to pass a WM_DESTROYCLIPBOARD 
message to I/O procedure for appropriate 
action. It is an optional message and may 
not be supported by an I/O procedure. 
Any errors should be ignored by the 
caller. 
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Storage System I/O Procedures 

A storage system procedure is an I/O procedure that “unwraps” a data object 
for a file format procedure to access. Storage system procedures are unaware of 
the format of the data object contained within the wrapper. A standard storage 
system I/O procedure is the DOS storage system procedure, which acts as an 
interface to the OS/2 operating system file system. This is typically the FAT or 
HPFS file system accessed through the OS/2 DosOpen , DosRead , DosWrite , 
and DosClose file services. 

A storage system consists of any type of storage mechanism that allows for a 
concept of a file that can be retrieved, manipulated, and saved as its own entity 
within the storage system. This includes file system, memory, network, data¬ 
base storage systems, and any other systems that fall into this category. For 
example, a memory storage system would contain memory files. A memory 
storage system is a virtual concept that provides a way for an application to 
deal with data through a block of memory. This memory contains data in the 
format that simulates a file as stored on a secondary device. This can be very 
useful for applications that want to generate data and provide it to MMPM/2 
as a memory file. 

Two APIs can be used to identify storage system I/O procedures: 
mmioDetermineSSIOProc and mmioIdentifyStorageSystem. These are 
typically used by an application or file format I/O procedure to identify the 
storage system that should be used to process a file. There are four main stor¬ 
age system I/O procedures available: 

• DOS storage system I/O procedure (DOS) 

• Memory storage system I/O procedure (MEM) 

• Compound storage system I/O procedure (CF and BND) 

® Quality of service network storage system I/O procedure (extended DOS) 

DOS and MEM Storage Systems 

The DOS storage system handles all standard OS/2 disk file system access. 
This is typically the FAT or HPFS file system accessed through the OS/2 
DosOpen , DosRead , DosWrite , and DosClose file services. The memory stor¬ 
age system I/O procedure manages memory files without accessing the file sys¬ 
tem. A memory file is a block of memory that is perceived as a file to an appli¬ 
cation. This unifies the interface for applications that access both memory and 
files. The DOS and MEM storage system I/O procedures support the following 
messages: 
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• The Basic I/O Procedure Messages (MMIOM.OPEN, MMIOM_CLOSE, 
MMIOM_GETFORMATNAME, MMIOM_GETFORMATINFO, 
MMIOM_IDENTIFYFILE) 

• mmiom.read 

• MMIOM_WRITE 

• MMIOM.SEEK 

Compound File Storage System 

MMIO supports the concept of compound (or bundled) files. A compound file is 
a file that can contain multiple file elements. A file element is an individual 
file or data object. Individual files can consist of a RIFF, a non-RIFF data file, 
a RIFF chunk, or just data. For example, a file element could consist of a wave¬ 
form audio file, or a movie file. Compound files can be viewed as wrappers to 
existing file formats. They are file format independent. MMIO provides ser¬ 
vices to add, remove, find, access, and compact elements within a compound 
file. MMIO in conjunction with the compound file (CF) and bundled file (BND) 
I/O procedures performs the unwrapping of the compound file to provide access 
to an individual element. The compound file and bundled file I/O procedures 
work together to provide the compound file support and can be viewed as one 
logical compound file I/O procedure. 

This concept is very useful in that existing applications and file format I/O 
procedures can deal with individual elements within a compound file as if they 
were standalone DOS files. The fact that the file element is actually contained 
within a compound file is hidden from the I/O procedure processing the file ele¬ 
ment. This concept allows any type of file or data to be stored and manipulated 
as an element in a compound file. 

One of the advantages of compound files is that applications that deal with 
many small multimedia data files can group them into a compound file, creat¬ 
ing a kind of data base of multimedia files. This can reduce the number of files 
the application deals with as well as frees the application from maintaining 
lists of files. The compound file structure already contains a table of contents 
for the file. This table of contents can be extended by the application to store 
application specific information. 

The compound file format is based on RIFF and hence can take advantage of 
any of the RIFF file management APIs provided by MMIO. A compound file 
always begins with two chunks. The first is the CGRP or file resource group. 
The second is the CTOC or Table of Contents. The rest of the file is made up of 
the individual elements. The file resource group contains all of the compound 
file element concatenated together into one RIFF chunk. The table of contents 
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is an index into the CGRP. For each file element, it contains an element name, 
where the element physically resides in the CGRP chunk, and other informa¬ 
tion about the element. The entries in the CTOC are extendible to contain 
other information that could be useful for an application. All CTOC entries 
must be the same size, but the application can specify the size of the entry and 
interpret it in its own way. 

Compound files can be used in the following manner: The mmioOpen API 
can be used to open a compound file element if the compound file name and the 
element are specified together in the form, “Compound_file.BND+ 
Element_name.” For example, cf.bnd+boing.wav would represent an open of 
the compound file cf.bnd followed by an open of the boing.wav file. The CF 
and BND I/O procedures unwrap the element and use the WAVE I/O procedure 
to open and interpret the boing.wav file. To the application, it appears as one 
open of a waveform file. Existing application should be able to take advantage 
of compound files without change. This is the case, unless the application 
manipulates the file names and tries to interpret the “+” compound file opera¬ 
tor. BND is also the four-character code (FOURCC) of a bundled file. 

On the other hand, if only a compound file name is specified on the 
mmioOpen API, then it will be interpreted as a RIFF file. It will be the job of 
the application to understand the chunks and manipulate them. It will not be 
viewed as a compound file to the system. 

The following is a list of compound file APIs that are provided by MMIO: 

Compound File APIs: 


mmioCFOpen 

mmioCFClose 

mmioCFGetlnfo 

mmioCFSetlnfo 

mmioCFAddEntry 

mmioCFChangeEntry 

mmioCFFindEntry 


This API adds an element to the CGRP chunk of 
an open RIFF compound file. 

This API closes a RIFF compound file that was 
opened by mmioCFOpen. 

This API retrieves the CTOC header of an open 
RIFF compound file. 

This API modifies information that is stored in 
the CTOC header of an open RIFF compound file. 

This API adds an entry to the CTOC chunk of an 
open RIFF compound file. 

This API changes a CTOC entry in an open RIFF 
compound file. 

This API finds a CTOC entry in an open RIFF 
compound file. 
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mmioCFDeleteEntry 

mmioCFAddElement 

mmioCFCopy 

mmioCFCompact 

mmioCFFindElement 


This API deletes a CTOC entry in an open RIFF 
compound file. 

This API adds an element to the CGRP chunk of 
an open RIFF compound file. 

This API copies the CTOC and CGRP chunks 
from an open RIFF compound file to another 
RIFF compound file. 

This API compacts the elements of a RIFF com¬ 
pound file by removing elements marked as 
deleted. 

This API enumerates the entries of a compound 
file. This is a 16-bit function and is used in 
conjunction with the audio macro interfaces to 
enable 16-bit applications easily with 
multimedia. 


mmioCFRemoveElement This API removes the specified element in a com¬ 
pound file. This is a 16-bit function and is used in 
conjunction with the audio macro interfaces to 
enable 16-bit applications easily with 
multimedia. 


Creating a Compound File 

The following code sample shows how to create a compound file. It shows the 
easiest way to create a compound file using existing data files. The 
mmioCFOpen , mmioCFAddElement , and mmioCFClose APIs are used in 
this sample. The sample will copy an audio and movie file to a created com¬ 
pound file. The final compound file will contain two elements, one for the audio 
file and one for the movie file. Each element is useable through the MCI inter¬ 
face using the element notation for compound files (for example, 
cf.bnd+boing.wav or cf.bnd+macaw.avi). This is one of the nice features of 
compound files. It can be used to combine many individual files into one large 
file. Since the compound file unwrapping is hidden from both the application 
and the file format I/O procedure, all file formats can take advantage of com¬ 
pound files. 



Using Multimedia I/O 153 


ULONG ulRc = 0; 

FILE *stream; 

CHAR buffer[8192]; 

int num; 

HMMCF hmmcf; 

MMCFINFO mmcfinfo; 

MMI0INF0 mmioinfo; 

PCHAR pbuffer = 0; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Create a Compound file with 4 RIFF WAVE files as elements 
Sample\n\n”); 

/* copy the boing.wav audio file to a compound file element */ 
if ((stream = fopen(“e:Wmmos2\\sounds\\boing.wav”, “rb”)) == NULL) { 

/* error */ 

printf(“Could not open audio data file\n”); 
goto end; 

} 


/* Allocate enough space for the file */ 
pbuffer = (PCHAR) malloc (110*1024); 

/* Read the file into a buffer to add */ 

/* as an element to a compound file */ 

num = fread(buffer, sizeof(CHAR), 8192, stream); 

if ( num ) { /* fread success */ 

printf( “Number of characters has been read = %i\n”, num ); 
fclose( stream ); 


/* Create a compound file and add an element */ 

hmmcf = mmioCFOpen(“e:\\mydir\\book\\code\\cf\\cf.bnd”, NULL, NULL, 
MMIO_CREATE + MMI0_WRITE); 

ulRc = mmioCFAddElement(hmmcf,’’boing.wav”,FOURCC_RIFF,buffer,num,0); 
ulRc = mmioCFClose(hmmcf,0); 

/* copy the macaw.avi movie file to a compound file element */ 
if ((stream = fopen(“e:\\mmos2\\movies\\macaw.avi”, “rb”)) == NULL) { 
/* error */ 

printf(“Could not open movie data file\n”); 
goto end; 


/* Allocate enough space for the file */ 
pbuffer = (PCHAR) malloc (110*1024); 


Figure 4-26. Creating a Compound File Sample 
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/* Read the file into a buffer to add */ 

/* as an element to a compound file */ 

num = fread(pbuffer, sizeof(CHAR), 110*1024, stream); 

if ( num ) { /* fread success */ 

printf( “Number of characters has been read = %i\n”, num ); 
fclose( stream ); 


/* Open the compound file and add another element */ 
hmmcf = mmioCFOpen(“e:\\mydir\\book\\code\\cf\\cf.bnd”, 

NULL, NULL, MMI0_WRITE); 

ul Rc = mmioCFAddEl ement(hmmcf,“macaw.avi”,FOURCC_RIFF,pbuffer,num,0); 
ulRc = mmioCFClose(hmmcf,0); 

end: 

if (pbuffer) 

free((PV0ID)pbuffer); 

printf (“ END: Create a Compound file with 4 RIFF WAVE files as elements 
Sample\n\n”); 


Figure 4-26. Creating a Compound File Sample (Continued) 

Querying Entries in a Compound File 

The following code sample shows how to query the contents of a compound file. 
Basically, this sample shows how to find what elements exist in a specific com¬ 
pound file. This sample will use the mmioCFOpen, mmioCFGetlnfo , 
mmioCFFindEntry , and mmioCFClose APIs to query the compound file 
table of contents for the element list in the file. 


ULONG ulRc = 0; 

HMMCF hmmcf; 

PMMCTOCENTRY pmmctocentry = 0; 

PMMCFINFO pmmcfinfo = 0; 

ULONG ulBytes = 0; 

ULONG ulFlags; 

PSZ pszElementName; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Find an entry in a Compound file Sample\n\n”); 

/* Open the compound file to search */ 

hmmcf = mmioCFOpen(“e:\\mydir\\book\\code\\cf\\cf.bnd”. 


Figure 4-27. Querying a Compound File Sample 
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NULL, NULL, MMIO_READ); 

/* Get # bytes for a CTOC entry from CTOC header of file. */ 

/* First query the real size of the CTOC header and then */ 

/* query the CTOC header to determine the size of the CTOC entry */ 

/* Fill in ulBytes with true length of mmcfinfo data */ 

ulRc = mmioCFGetInfo(hmmcf, (PMMCFINF0)&ulBytes, sizeof(ULONG)); 

if (ulRc != sizeof(ULONG)) { 

/* error */ 
goto end; 

} 


/* Get CTOC header of file */ 

pmmcfinfo = (PMMCFINFO) malloc (ulBytes); 

memset(pmmcfinfo, ‘\0’, ulBytes); 

ulRc = mmioCFGetInfo(hmmcf, pmmcfinfo, ulBytes); 

/* Determine the size of a ctoc entry */ 
ulBytes = pmmcfinfo->usEntrySize; 
pmmctocentry = (PMMCTOCENTRY) malloc (ulBytes); 

/* Find all entries in ctoc */ 
ulFlags = MMI0_ FINDFIRST; 
memset(pmmctocentry, ‘\0’, ulBytes); 
ul Rc = 0; 
while (!ulRc) { 

/* Query one entry */ 

ulRc = mmioCFFindEntry(hmmcf.pmmctocentry,ulFIags); 
if (! ul Rc) { 

pszElementName = (PSZ)(pmmctocentry+1); /* Ptr arithmetic */ 
printf (“CTOC ENTRY: size =%d, name=%s\n”,pmmctocentry->ulSize, 
pszElementName); 
ulFlags = MMI0_FIN DN EXT; 

/* Must leave previous entry in the CTOC passed to */ 

/* mmioCFFindEntry for the MMI0_FIN DN EXT to find */ 

/* the next entry correctly */ 

} 

} /* endwhile */ 

if (ulRc != MM 10 E RR_CF_ENTRY_NOT_FOUND) { 

/* Error */ 
goto end; 


end: 

if (pmmcfinfo) 


Figure 4-27. Querying a Compound File Sample (Continued) 
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free((PVOID)pmmcfinfo); 
if (pmmctocentry) 

free((PVOID)pmmctocentry); 

ulRc = mmioCFClose(hmmcf,0); 

printf (“ END: Find an entry in a Compound file Sample\n\n”); 


Figure 4-27. Querying a Compound File Sample (Continued) 

Quality of Service Network Storage System 

Quality of service, or QOS, is a term used to describe a feature of some net¬ 
works that provide the ability to guarantee certain attributes of data transfer 
across a network. With the popularity of multimedia, audio and movie files 
have proliferated, and these files tend to consume large amounts of disk space. 
Because of this, the ability to remotely access and play these files is becoming 
more important. On most networks, data transfers are typically not guaran¬ 
teed to occur within a specific time period. This can cause the remote playback 
of an audio file to breakup and this is very undesirable. Remotely playing 
movie files tend to be worse because of the required bandwidth to transfer 
video and audio data across a network. 

To resolve these types of problems, some network software and hardware 
provide the ability to reserve bandwidth on the network so that the data trans¬ 
fer of multimedia data can occur without breakup. This is referred to as quality 
of service. A network that supports this type of connection has a maximum 
bandwidth and therefore, cannot always grant requests for reserved bandwidth 
after the maximum amount has already been reserved. Some specialized forms 
of OS/2 network software provide support to MMPM/2 I/O procedures for quali¬ 
ty of service functionality. (Refer to the IBM LAN Server Software products). 
This is an extended DOS storage system I/O procedure that supports the fol¬ 
lowing two messages: 

Quality of Service (QOS) Messages: 

MMIOM_BEGINSTREAM Set the quality of service parameters and acti¬ 
vate quality of service for network I/O. 

MMIOM_ENDSTREAM This message deactivates the quality of service 

for network I/O. 

MMIOMJBEGINSTREAM and MMIOMJENDSTREAM are used to 
reserve and release network bandwidth. The MMIOMJBEGINSTREAM mes¬ 
sage provides the ability to set four types of quality of service parameters: 
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service.request 


MAX_EE_ JITTER 


MAX_DATA_RATE 

AVG_DATA_RATE 


This QOS parameter requests the type service 
required for a data transfer across the network. 
There are three types of services to request: 
GUARANTEED, DONTCARE, and DONTRE- 
SERVE. GUARANTEED indicates that the 
application request for quality of service should 
fail if, for some reason, guaranteed service can¬ 
not be satisfied or this type of service is not avail¬ 
able. This means that the network connection 
will not be made with the remote machine. 
DONTCARE indicates that the application 
request for quality of service should be granted if 
available, but if it is not available, a connection 
will be made without quality of service band¬ 
width reservation. This means that the QOS is 
important, but not so important that the data 
transfer should not take place. For example, the 
remote playback of an audio or movie files may 
breakup if the DONTCARE type of service is 
specified on this message. DONTRESERVE 
indicates that the application does not require 
guaranteed quality of service. This is the default 
for the storage system I/O procedures, if the 
MMIOM_BEGINSTREAM message is not 
received. 

This describes network jitter, which is a term for 
a value that is used to represent the difference 
between the maximum and minimum data trans¬ 
fer latency between two machines on a network. 
The generic calculation for MAX_EE_JITTER is 
(buffer size - x)/maximum transfer rate. Where x 
is the number of bytes required for a single data 
unit (e.g., # of bytes for a frame of video). 

This QOS parameter indicates the maximum 
data rate in bytes per second for the data 
transfer. 

This QOS parameter indicates the average data 
rate in bytes per second for the data transfer. 
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In a typical scenario, all four parameters must be set. The quality of service 
MMIOM_BEGINSTREAM and MMIOM_ENDSTREAM messages are 
passed from an application to a file format I/O procedure, which in turn, will 
pass these messages to the storage system I/O procedure. File format I/O pro¬ 
cedures must be able to pass on any messages they cannot handle to the stor¬ 
age system I/O procedure. This standard practice for I/O procedures, frees the 
file format I/O procedures from having to know about or implement quality of 
service. 

For the best results with respect to network responsiveness, the begin 
stream request should not be performed until the data transfers are requested 
to begin. Usually, it is necessary to open the file and possibly read some file 
headers and other information pertaining to the data within a file as setup to 
any data transfers. These operations should be performed before an 
MMIOMJBEGINSTREAM message is issued. Once the quality of service has 
been activated, it is advantageous to avoid seek operations on the file being 
transferring across the network. The data should be accessed in a serial fash¬ 
ion to achieve the best performance. 

Applications using the MCI interfaces for playback or record, can take 
advantage of this functionality within the media control drivers. The quality of 
service interfaces only need to be used for data transferred done explicitly 
through the MMIO interface. For example, in frame-step video capture, the 
application is responsible for using the MMIO interfaces directly to write the 
captured audio and video data to a file. In this case, if a capture is done over a 
network, the quality of service functionality would be useful. 

The SERVICE JREQUEST parameter for quality of service can be set using 
the value returned from a mciQuerySysValue API call to request this infor¬ 
mation from the MMPM2.INI file. The MMPM2.INI file contains information 
that describes the streaming quality when files are played or recorded over a 
network. This information is saved in the MMPM2.INI file when a storage sys¬ 
tem I/O procedure that provides quality of service is installed in the system. 
The MMPM2.INI file contains two variables that an application can retrieve. 
The first one, MSV.SYSQOSVALUE, contains the recommended type of ser¬ 
vice required for a data transfer across the network. This maps to the SER- 
VICE_REQUEST parameter of MMIOM_BEGINSTREAM. If this quality of 
service is not available, then another variable MSV_SYSQOSERRORFLAG 
describes whether or not to notify the caller with an error. 

The following code sample shows how to query the MMPM2.INI file for the 
type of service and the error information. It also shows how to query a movie 
file for the appropriate information needed to set the QOS parameters on the 
MM[IOM_BEGINSTREAM message: 
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typedef struct { 

QOSInfo QOSParms; 

QOS Q0SItem[4]; 

} MY_Q0S; 

ULONG 
MMIOINFO 
HMMIO 

PMMMOVIEHEADER 
PMMVIDEOHEADER 
PMMAUDIOHEADER 
LONG 
LONG 
MY_QOS 
ULONG 
ULONG 
ULONG 
doubl e 

system(“cls”); 
printf(“\n\n”); 
printf (“ START: Set Quality of Service Sample\n\n”); 

/* Query the MMPM2.INI file to determine if QOS is available */ 
/* and if not, should an error be returned to the application*/ 

ulRc = mciQuerySysValue(MSV_SYSQOSVALUE, &lQOSValue); 
if (!u1Rc) { /* Variable not found */ 

IQOSValue = DONTRESERVE; 


ulRc = mciQuerySysValue(MSV_SYSQOSERRORFLAG, &1QOSReporting); 
if (!ulRc) { /* Variable not found */ 

1QOSReporting = ERROR_DEFAULT; 

} 

ulRc = 0; /* Reset this after mciQuerySysValue */ 

/* Open the file and read the header for the information needed to */ 
/* set the quality of service parameters */ 

/* Open the file with header translation */ 
memset(&mmioinfo, ‘\0’, sizeof(MMIOINFO)); 
mmioinfo.ulTranslate = MMIO_TRANSLATEHEADER; 
mmioinfo.fccIOProc = mmioFOURCCC‘A’,’V’,’I’, ’ *); 
hmmio = mmio0pen(“e:\\mmos2\\movies\\macaw.avi’\ &mmioinfo, 
MMIO_READWRITE); 

/* Check for error */ 


Figure 4-28. Quality of Service Usage Sample 


ul Rc = 0; 
mmioinfo; 
hmmio = 0; 
pMovieHdr = 0; 
pVideoHdr = 0; 
pAudioHdr = 0; 
IQOSValue; 

1QOSReporting; 
myQOS; 

ulAverageRate; 
ulMaxRate; 
ulFrameSize; 
fps; 




160 Developing Multimedia Applications Under OS/2 


if (Ihmmio) { 

/* error */ 

printf(“Error, mmioOpen failed.\n”); 
goto end; 


/* Get the video track header for necessary information to set QOS */ 
ulRc = GetMovieFileHeaders(hmmio,&pMovieHdr,&pVideoHdr, 

&pAudioHdr,0,0); 

if (ulRc || IpVideoHdr) { /* error or no video hdr */ 

/* error */ 

printf(“Error, GetMovieFi1eHeaders failed.\n”); 
goto end; 


/* Determine and set the Quality Of Service parameters */ 

myQOS.QOSParms.1NumQOSParms = 4; /* Four QOS parameters */ 

/* Set of type of request (queried from MMPM2.INI file) */ 
myQOS.QOSParms.QOSParms[0].1QOSParmld = SERVICE_REQUEST; 
myQOS.QOSParms.QOSParmsEO].1QOSValue = lQOSValue; 

/* Access Video Track Header to get infomation for QOS calls */ 
fps = ((double)(pVideoHdr->ulRate) / (double)(pVideoHdr->ulScale)); 

/* Access Movie Header to get infomation for QOS calls */ 
ulAverageRate = pMovieHdr->ulAvgBytesPerSec; 
ulFrameSize = (ULONG) ((double) (ulAverageRate) / fps + 0.5); 
ulMaxRate = pMovieHdr->ulMaxBytesPerSec; 

if (ulMaxRate < ulAverageRate) /* Some Movies have incorrect max */ 
ulMaxRate = ulAverageRate; 

/* Set the jitter parameter (assume buffer size of 128k) */ 
myQOS.Q0SItem[0].1QOSParmld = MAX_EE_JITTER; 

myQOS.QOSItemEO].lQOSValue = ( 128*1024 - ulFrameSize) / ulMaxRate; 

/* Set the maximum data rate parameter */ 
myQOS.QOSItemEl].1QOSParmld = MAX_DATA_RATE; 
myQOS.QOSItemEl].1QOSValue = ulMaxRate; 

/* Set the average data rate parameter */ 
myQ0S.Q0SItemE2].1QOSParmld = AVG_DATA_RATE; 
myQOS.Q0SItemE2].1 QOSV a 1ue = ulAverageRate; 

/* Set the Quality Of Service parameters */ 

ulRc = mmioSendMessage(hmmio, MMIOM_BEGINSTREAM, STREAM_READ, 

Figure 4-28. Quality of Service Usage Sample (Continued) 
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(LONG)&myQOS); 

if ( ulRc && ulRc != MMIOERR_UNSUPPORTED_MESSAGE ) { 

/* Use the 2.INI 1QOSReporting value queried above */ 
if (1QOSReporting == ERR0R_REP0RT) { 

/* Report the Error */ 
goto end; 


ulRc = 0; /* Ignore if unsupported */ 


/* DO DATA TRANSFER - HERE */ 


/* End Quality Of Service */ 

ulRc = mmioSendMessage(hmmio, MMIOM_ENDSTREAM, 0,0); 
end: 

if (hmmio) 

ulRc = mmioClose(hmmio,0); 

CleanupMovieHeaders(pMovieHdr, pVideoHdr, pAudioHdr); 
printf (“ END: Set Quality of Service Sample\n\n”); 


Figure 4-28. Quality Of Service Usage Sample (Continued) 

CODEC Procedures 

A CODEC is an algorithm used to either compress data into a smaller space, or 
decompress some compressed data back into the original or close approxima¬ 
tion of the original data, in some cases. Two types of CODEC procedures are: 
Compressor and Decompressor. MMPM/2 currently supports image and digital 
video CODECs. MMPM/2 does provides a set of audio CODECs, but MMPM/2 
does not yet provide a public interface to install new audio CODECs or to inter¬ 
face to them directly. They are used internally within MMPM/2 for playing 
audio and movie files that contain compression audio. 

A CODEC procedure can be used directly by an application, or indirectly 
through a file format I/O procedure using CODEC access messages. A file for¬ 
mat I/O procedure may use a CODEC procedure to implement data transla¬ 
tion. The MMIOM.COMPRESS and MMIOMJDECOMPRESS CODEC 
access messages are used for this purpose. MMPM/2 takes advantage of this 
capability on playback of movies and on real-time video capture. The other sub¬ 
systems of MMPM/2 will indirectly interface with the CODEC procedure 
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through the file format I/O procedure being used. An application can also do 
the same thing, as in the case of a frame-step video capture. A video capture 
application would interface to the CODEC indirectly. Using the file format 
CODEC access messages is useful, in that the file format I/O procedure is able 
to interpret and unwrap any file format specific headers attached to video 
frames before they are passed to a CODEC procedure. This allows the system 
to pass the native headers with the video frame, maintaining necessary infor¬ 
mation to be interpreted as a frame is decompressed. Typically, a CODEC 
procedure is file format-independent, so it would not understand native file 
headers. 


CODEC Access Message Usage 



Figure 4-29. CODEC Access Message Usage 
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Types of CODECs 

A CODEC can be either a software or hardware CODEC. A software CODEC is 
one that is executed solely in software. A hardware CODEC is one that consists 
of some level of hardware assistance to compress or decompress data. The 
MPEG-1 decompressor is a good example of a hardware CODEC. The MPEG-1 
decompression is done solely in hardware. The compressed video frames are 
passed to the decompressor, which transfers them to the hardware, which then 
decompresses the video and displays it on the video monitor. A hardware 
CODEC is identified by a bit flag in the ulCapsFlags field of the 
CODECINIFILEINFO data structure. 

It is possible to have multiple CODECs that decompress or compress the 
same data installed in the system at one time. For example, in one case, there 
may be a hardware and software CODEC (decompressor) for MPEG-1 installed 
in the system. Selecting the hardware CODEC instead of the software CODEC 
on systems that have both is desirable. This can be done by checking the capa¬ 
bility flag in the CODECINIFILEINFO data structure before loading a 
CODEC. 

Digital Video CODECs 

The following table contains a list of currently supported CODECs that are 
available with the OS/2 Warp version of MMPM/2. 


Digital Video 

CODEC 

SW/HW 

Real-time 

Asymmetric 

Editing 

CODECs 

FOURCC 

Decompression 

Compression Compression 

Enabled 

Ultimotion 

ULTI 

sw 

yes 

yes 

yes 

Indeo 2.1 

RT21 rt21 

sw 

yes 

yes 

yes 

Indeo 3.1 

IV31 iv31 

sw 

yes 

yes 

yes 

Indeo 3.21 

V32 iv32 

sw 

no 

no 

no 

FLC/FLI 

FLIC 

sw 

no 

no 

no 

MPEG-1 

MPEG 

hw 

no 

no 

no 

RAW 

DIB 

sw 

yes 

yes 

yes 


Table 4-3. Digital Video CODECs 
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Installing CODEC Procedures 

Before a CODEC procedure can be used by the MMIO subsystem, it will need 
to be installed in the system. Since MMIO services are based on individual 
CODEC procedures being available as loadable DLLs, there exists a list of 
known and usable CODEC procedure DLLs. All of the available CODEC proce¬ 
dures are identified or listed in the MMPMMMIO.INI file. MMPM/2 does pro¬ 
vide a set of pre-installed CODEC procedures. Other products, such as Video 
IN, install their own CODEC procedures when they are installed in the sys¬ 
tem. Application writers may also want to install additional CODEC proce¬ 
dures as well. Therefore, MMIO provides a way to install CODEC procedures 
into the MMPMMMIO.INI file. Unlike I/O procedures that have several meth¬ 
ods of installation, CODEC procedures can only be installed permanently. A 
CODEC DLL can be loaded by using DosLoadModule and called directly, 
however, if the entry point is known. Use the mmioIniFileCODEC to install a 
CODEC procedure into the MMPMMMIO.INI file permanently. The 
mmioIniFileCODEC API can also be used to replace, remove or find an entry 
in the MMPMMMIO.INI file. 

Once a CODEC procedure has been added to the MMPMMMIO.INI file, it 
can be loaded and used. Each CODEC has a set of properties or capabilities. 
These values are stored in a data structure called CODECINIFXLEINFO. 
This data structure contains the information that is stored in the MMPMM¬ 
MIO.INI for each CODEC. The ulCompressType field contains the CODEC 
FOURCC. 


typedef struct _C0DECINIFILEINFO { 

/* 

codecinifi1ei nfo 

*/ 

ULONG 

ulStructLen; 

/* 

length of this structure 

*/ 

FOURCC 

fee; 

/* 

File Format ID 

*/ 

CHAR 

szDLLName[DLLNAME_SIZE]; /* 

r DLL name string 

*/ 

CHAR 

szProcName[PROCNAME_ 

SIZE] ; 

/* Procedure name string 

*/ 

ULONG 

ulCompressType; 

/* 

Compression Type 

*/ 

ULONG 

ulCompressSubType; 

/* 

Compression SubType 

*/ 

ULONG 

ulMediaType; 

/* 

Media type 

*/ 

ULONG 

ulCapsFlags; 

/* 

capabilities flags 

*/ 

ULONG 

ul FI ags; 

/* 

fl ags 

*/ 

CHAR 

szHWID[CODEC_HW_NAME 

_SIZ E ] ; 

; /* specific information 

*/ 

ULONG 

ulMaxSrcBufLen; 

/* 

max source buffer length 

*/ 

ULONG 

ulSyncMethod; 

/* 

Synchronization method 

*/ 

FOURCC 

feePreferred Format; 

/* 

Preferred output format 

*/ 

ULONG 

ulXalignment; 

/* 

x alignment - video only 

*/ 

ULONG 

ulYalignment; 

/* 

y alignment - video only 

*/ 


ULONG ulSpeclnfo[C0DEC_INF0_SIZE]; /* specific information */ 

} CODECINIFILEINFO; 
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A particular CODEC procedure can be associated with different file formats. 
Typically, each file format that uses a CODEC must have a separate entry in 
the MMPMMMIO.INI file. Sometimes it is possible to have several types of the 
same CODEC. This can be the case when several file formats have a CODEC 
with the same identifier (FOURCC), but in actuality, each one is referring to a 
separate CODEC procedure. Therefore, indicating a file format FOURCC, the 
fee field, with each CODEC entry in the MMPMMMIO.INI file is necessary. 
This provides the flexibility to have several CODEC procedures with the same 
FOURCC, but each one is specific to a file format. (Note: This book does not 
discuss how to write a CODEC procedure. Refer to the IBM MMPM/2 publica¬ 
tions and toolkit for more information on writing a CODEC.) 

Loading a CODEC Procedure 

MMIO provides an API to load a CODEC, mmioLoadCODECProc . This API 
is used to load the CODEC into memory and return the entry point for the 
CODEC. The entry point can then be used to sent MMIOM_CODEC_ mes¬ 
sages to the CODEC. This API is typically used by an I/O procedure to load a 
CODEC when a movie file is opened for playback (read or readwrite) or when a 
CODEC is associated with a video track in a movie track. A CODEC can be 
associated when creating a new movie file or when the CODEC opened for 
playback needs to be changed based on the desired output. An application 
would only need to use this API when interfacing with the CODEC directly. In 
almost all cases, an application would use the file format I/O procedure 
CODEC access messages to indirectly interface to the CODEC. This allows the 
file format I/O procedure to filter out file format specific information when 
reading video data from a file. Therefore, an application should let the file for¬ 
mat I/O procedure load the CODEC. 

CODEC Procedure Messages 

A CODEC can be used in one of two ways, either directly or indirectly through 
a file format I/O procedure CODEC access messages as discussed previously. 
CODEC procedures can be loaded and called directly by using the 
mmioLoadCODECProc API, which will return the entry point for the 
CODEC. A call to this entry point with an MMIOM_CODEC_OPEN message 
will return an HCODEC, which will be used to identify the open instance on 
all other calls to the CODEC. The syntax for a direct CODEC procedure call is 
as follows: 
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typedef LONG (APIENTRY CODECPROC) (PHCODEC phcodec, 

USHORT usMsg, 

LONG IParml, 

LONG 1Parm2); 

typedef CODECPROC *PCODECPROC; 

All CODEC procedures must support the following messages. There are no 

optional messages other then a CODEC can be a decompressor and/ or a com¬ 
pressor. In the case where a CODEC can only be used as a decompressor, then 

the MMIOM_CODEC_COMPRESS message does not need to be supported. 

This also applies to the reverse case. 

CODEC Messages: 

MMIOM_CODEC_OPEN This message requests that a 

CODEC be opened. 

MMIOM_CODEC_CLOSE This message requests that a 

CODEC opened by MMIOM_ 
CODEC_OPEN be closed. 

MMXOM_CODEC_QUERYNAME This message requests the name 

of CODEC. 

MMIOM_CODEC_QUERYNAMELENGTH This message requests the length 

of the name for a CODEC. 

MMIOM_CODEC_COMPRESS This message requests that data 

be compressed by the CODEC. 
Compression CODEC procedures 
only. 

MMIOM_CODEC_DECOMPRESS This message requests that data 

be compressed by the CODEC. 
Decompression CODEC proce¬ 
dures only. 
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Querying CODEC Procedure Information 

Video oriented applications that deal with different types of digital video com¬ 
pression, primarily content creation applications will be interested in present¬ 
ing a list of possible Compression CODECs to the user. This can be accom¬ 
plished by querying the compression CODECs that match your search criteria. 
Each CODEC has a CODECINIFILEINFO entry in the MMPMMMIO.INI 
file. MMIO provides a service, the mmioIniFileCODEC API, to search the 
MMPMMMIO.INI file for CODECs based on a variety of different characteris¬ 
tics. Only some fields are used for searching and each field is pattern matched 
in a different way; some are exact matches and some are bit flag inclusion 
matches. The following list of flags are used to define the search criteria: 

CODEC Search Criteria: 

MMIO_MATCHCOMPRESSTYPE Use the ulCompressType field of 

CODECINIFILEINFO to match 
the CODEC FOURCC identifier. 
This is an exact match. 

MMIO.MATCHCOMPRESSSUBTYPE Use the ulCompressSubType field 

of CODECINIFILEINFO to 
match the CODEC subtype. This is 
an exact match. 

Use the szHWIDO field of 

CODECINIFILEINFO to match 
the hardware ID. This is an exact 
match. 

Use the ulCapsFlags field of 
CODECINIFILEINFO to match 
the capabilities. A CODEC is con¬ 
sidered a match if the bits flags set 
in this field are set for the CODEC 
entry. 

Use the fee field of 

CODECINIFILEINFO to match 
the file format FOURCC. This is 
an exact match. 

Use the szDLLNamef] field of 

CODECINIFILEINFO to match 
the CODEC DLL name. This is an 
exact match. 


MMIOJVtATCHHWID 


MMIO.MATCHCAPSFLAGS 


MMIO.MATCHFOURCC 


MMIO.MATCHDLL 
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MMIO.MATCHPROCEDURENAME Use the szProcNameO field of 

CODECINIFILEINFO to match 
the CODEC entry point procedure 
name. This is an exact match. 

The following code sample shows one of the uses of mmioIniFileCODEC 
API which searches for all CODECs in the system. It also uses the 
mmioQueryCODECName and mmioQueryCODECNameLength to display 
the name of each CODEC. This sample has code that will search for the com¬ 
pressor CODECs first and then search for decompressor CODECs. Because of 
anomalies in the mmioIniFileCODEC API search logic, it is not possible to 
query, find first and find next, for all CODECs in one series of calls. The search 
should be broken up into two sets of mmioIniFileCODEC calls—one for com¬ 
pressors and one for decompressors. CODECs that are both will show up in both 
searches, so duplicate checking should be done by an application, just in case. 
The search for all decompressor is actually broken up into four parts. Each part 
searches for CODECs that output to a particular color space. This four part 
search for decompressors is necessary to find all of the decompressors. 


/*******************************************************************/ 


/* Query CODEC Procedures */ 
/* */ 
/* This routine searches for all of the decompressors or */ 
/* all of the compressors in the system. Currently, the */ 
/* mmioIniFileCODEC API can not be used to find all CODECs in the */ 
/* system. A search criteria must be set, otherwise the API */ 
/* defaults to doing an exact match. This causes the API to always */ 
/* return the same CODEC over and over again. Therefore, to get */ 
/* around this problem, specify the MMIO_MATCHCAPSFLAGS search */ 
/* criteria and find the compressors first, then the decompressors.*/ 


/*******************************************************************/ 
ULONG QueryCODECs(ULONG ulCapsFlags) 

{ 

ULONG ulRc = 0; 

CODECINIFILEINFO codecinifi1einfo; 

CODECINIFILEINFO codecinifi1einfoLast; 

PSZ pszCODECName = 0; 

PSZ pszFOURCC = 0; 

ULONG ulFlags; 

ULONG ulLength; 

ULONG ulBytesRead; 

/* Query for all CODEC Procedures */ 

memset(&codecinifi1einfo, ‘\0*, sizeof(CODECINIFILEINFO)); 

Figure 4-30. Querying CODECs Sample 
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memset(&codecinifi1einfoLast, ‘ \ 0 ’, sizeof(CODECINIFILEINFO)); 
codednifi1einfo.ulStructLen = sizeof(CODECINIFILEINFO); 
ulFlags = MMIO_FINDPROC+MMIO_MATCHFIRST+MMIO_MATCHCAPSFLAGS; 

/* Find each CODEC one at a time */ 
whi 1 e (!ulRc) { 

coded ni fi 1 ei nfo. ul CapsFl ags = ulCapsFlags; 

ulRc = mmiolniFi1eCODEC(&codecinifi1einfo, ulFlags); 

/* Check for infinite loop - NOTE: this is important, if this */ 

/* check is not done, infinite loop will occur in MMIO. */ 

if (memcmp(&codecinifi1einfo, 

&codecinifi1einfoLast, 
sizeof(CODECINIFILEINFO)) == 0) { 
ulRc = MMI0ERR_MATCH_N0T_F0UND; /* Force out of infinite loop */ 

} 

if (ulRc) { 

if (ulRc = MMI0ERR_MATCH_N0T_F0UND) { 

ulRc = 0; /* we are done - no error */ 

break; /* Get us out of here - now */ 

} else { 

/* error */ 

printf(“Error %d, mmiolniFi1eCODEC fai1ed.\n”,ulRc); 

} 

} else { /* If no error, found a CODEC entry */ 

/* Save last found entry */ 

memcpyC&codecinifi1einfoLast,&codecinifi 1 einfo, 
sizeof(CODECINIFILEINFO)); 

/* Query the CODEC name length and name */ 

ulRc = mmioQueryCODECNameLength(&codecinifi1einfo,&ul Length); 

if (ulRc) { 

/* Assume the CODEC does not support this message. */ 

/* Therefore, display the DLL name instead */ 
printf (“DLL Name=%s\n”, codednifi1einfo.szDLLName); 
ulRc = 0; /* Ignore Error */ 

} else { 

/* allocate space for name */ 

ulBytesRead = ulLength+1; 

pszCODECName = (PSZ) malloc (ulBytesRead); 

/* Get name string */ 

ulRc = mmioQueryCODECName(&codecinifileinfo,pszCODECName, 

&ulBytesRead); 

if (ulRc) { 

/* error */ 

printf(“Error %d, mmioQueryCODECName fai1ed.\n”,ulRc); 


Figure 4-30. Querying CODECs Sample (Continued) 
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if UulRc) { 

/* Display CODEC information */ 
if (ulBytesRead) 

printf (“Name=%s\n”, pszCODECName); 
pszFOURCC = (PSZ) &codecinifi1einfo.fee; 

printf(“ File Format FOURCC = \”%c%c%c%c\” \n”,pszFOURCC[0], 
pszFOURCCEl],pszFOURCC[2],pszFOURCC[3]); 
pszFOURCC = (PSZ) &codecinifi1einfo.ulCompressType; 
printf(“ Compression Type FOURCC = \”%c%c%c%c\” \n”, 

pszFOURCCEO],pszFOURCCEl],pszFOURCC[2],pszFOURCC[3]); 

/* Display media type */ 

switch (codecinifileinfo.ulMediaType) { 

case MMIO_MEDIATYPE_AUDIO: 

printf(“ Media Type = Audio \n”); 
break; 

case MM 10_M ED IATY P E_DIGITALVIDEO: 

printf(“ Media Type = Video \n”); 
break; 
default: 

printf(“ Media Type = %x \n”,codecinifi1einfo.ulMediaType) 
break; 

} 

printf(“ Capabilities Flags = %x \n”, 
codecinifi1einfo.ulCapsFlags); 

/* Display some fields of capabilities flag */ 
if (codecinifi1einfo.ulCapsFlags & CODEC_COMPRESS) 
printf(“ Can do compression\n”); 

if (codecinifi1einfo.ulCapsFlags & CODEC_DECOMPRESS) 
printf(“ Can do decompression\n”); 

if (codecinifi1einfo.ulCapsFlags & CODEC_SYMMETRIC) 
printf(“ Can do real-time compression\n”); 

if (codecinifileinfo.ulCapsFlags & CODEC_ASYMMETRIC) 
printf(“ Can do non-real-time compression\n”); 

printf(“\n”); 

/* free name space */ 
if (pszCODECName) 

free((PVOID)pszCODECName); 


} 

/* Find the next CODEC entry */ 

ulFlags = MMIO_FINDPROC+MMIO_MATCHNEXT+MMIO_MATCHCAPSFLAGS; 


Figure 4-30. Querying CODECs Sample (Continued) 
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return( ulRc); 

} 


^^^^^^^^^^■k^^^^-k'k-k'k-k'k-k'k-k^'k'k'k-k-k'k'k-k-k'k'k-k'k'k-k'k-k-k'k'k'k-k'k-k-k-k-k-k'k^-k'k-k-k'k'k'k'k'k'k'k'k'k J 


/* Query Decompressor CODEC Procedures */ 
/* */ 
/* NOTE: You must specify the Number of bits of color in addition */ 
/* to the decompress flag for this search to work. Otherwise,*/ 
/* the find next flag for mmiolniFi1eCODEC will cause it to */ 
/* infinite loop returning the same CODEC. Therefore, we */ 
/* need to make four calls to query all of the decompressors */ 
/* in the system. */ 


/-k-k-k*-k-k-k*-k'k-k-k-k-k-k'k-k-k'k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k'k-k*ic-k'k 'k*-k*-k'k'k-k-k-k'k-k-k-k-k-k'k-k-k-k'k-k'k-k'k-k j 

ULONG QueryDecompressorsCVOID) 

{ 

ULONG ulRc = 0; 

/* This routine may cause duplicates to be printed. Therefore, if */ 

/* using this same methodology to print a list, check for duplicates*/ 

/* and only save information once for duplicates. For example, the */ 

/* DIB CODEC will show up 4 times, once for each of these calls. */ 

ulRc = QueryCODECs(C0DEC_DEC0MPRESS+C0DEC_24_BIT_C0L0R); 
if (ulRc) { 

/* error */ 

printf(“Error %d, QueryC0DECs(decompressors+24_bit_color) failed.\n”, 
ulRc); 

} 

ul Rc = QueryCODECs(C0DEC_DEC0MPRESS+C0DEC_16_BIT_C0L0R); 
if (ulRc) { 

/* error */ 

printf(“Error %d, QueryC0DECs(decompressors+16_bit_color) failed.\n”, 
ulRc); 
goto QDend; 

} 

ul Rc = QueryCODECs(C0DEC_DEC0MPRESS+C0DEC_8_BIT_C0L0R); 
if (ulRc) { 

/* error */ 

printf(“Error %d, QueryC0DECs(decompressors+8_bit_color) failed.\n”, 
ulRc); 
goto QDend; 

} 

ulRc = QueryCODECs(C0DEC_DEC0MPRESS+C0DEC_4_BIT_C0L0R); 
if (ulRc) { 

/* error */ 

printf(“Error %d, QueryCODECs(decompressors+4_bit_color) failed.\n”, 
ulRc); 
goto QDend; 


Figure 4-30. Querying CODECs Sample (Continued) 



172 Developing Multimedia Applications Under 05/2 


} 

QDend: 

return(ulRc); 

} 


/**************************************************j 

/* Query CODEC Procedures installed in the system */ 

I'k'k-k'k-k'k-k'k-k-k-k-k-k'k-k'k-k-k-k'k'k'k'k-k'klt'k'k-k-k'k'k-k'k-k-k'kit'k'k'k-k-k-k-k-k-k-k-k'kj 

INT main( VOID ) 

{ 

ULONG ulRc = 0; 

system(“cls”); 
printf(“\n\n”); 

printf (“ START: Query CODEC Procedures installed in the system 
sample\n\n”); 

/* Get all Compressors */ 

ulRc = QueryCODECs(CODEC_COMPRESS); 

if (ulRc) { 

/* error */ 

printf(“Error %d, QueryCODECs(compressors) failed.An”,ul Rc); 
goto end; 

} 


/* Get all Decompressors */ 
ulRc = QueryDecompressors(); 
if (ulRc) { 

/* error */ 

printf(“Error %d, QueryCODECs(decompressors) fail ed.\n M ,ul Rc); 

} 

end: 

printf (“ END: Query CODEC Procedures installed in the system sample\n\n”) 
return( ulRc); 


Figure 4-30. Querying CODECs Sample (Continued) 
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INTRODUCTION 


In this chapter, we cover various topics about waveform audio, which is more 
commonly referred to as “digital waveaudio” or simply as “waveaudio.” To 
effectively use waveaudio, it is necessary to have some knowledge about basic 
audio theory. This will become apparent, given all the options the applications 
have. Also, knowing how to go about employing the audio playback and record¬ 
ing facilities within MMPM/2, what commands and functions are relevant to 
waveaudio, and how to utilize them is necessary. Our main goal here is to 
make the transition towards inclusion of audio support within an application 
as straightforward, and direct as possible. Adding waveaudio support to an 
application can be as simple as providing an audible cue for a selection the 
user makes within an application, or it can be a complex matter. How you wish 
to employ it is the main dictating factor. Consider the instance where various 
different sounds must be employed and managed in situations where you must 
switch from one to another as seamlessly as possible. Good forethought into 
how to organize and prepare your waveaudio content will also be a major con¬ 
sideration. Some care and planning should be put into how or where to best 
make use of it. If careful choices are not made about the content itself, not only 
can waveaudio become a major hindrance to your development effort, but to 
the usability of your application. 

A well designed and implemented multimedia application can be a real 
attention grabber. An application that either under-utilizes the possibilities of 
waveaudio in drawing the attention of the user, or utilizes so much of system 
resource to provide that audio support can become a costly mistake. In either 
case, the application may not only be perceived as dull or boring, but as user- 
hostile. 
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Understanding and taking into account the various levels of support for dif¬ 
ferent audio data types is very important. What type of waveaudio support is 
available varies from sound card to sound card. Given that only certain data 
types are supported on most cards, careful thought as to what type of content 
to create is also important to any developer. It should be apparent, that the 
process of enabling an application to utilize multimedia requires a good appli¬ 
cation design plan, and that consideration of multimedia’s requirements on the 
other parts of your application are just as important as any other part of the 
normal development process. In some cases, you may be dealing with content 
supplied by the user, in others you must author it yourself, and certain 
accountability for each should be made. 

The process of recording waveaudio data to some may seem a bit daunting. 
“What playback rate should be used?” “Stereo or mono?” “Is 8-bit quality good 
enough?” are all important questions. As was stated in the introduction to the 
book, most multimedia data types, can require a considerable amount of stor¬ 
age space. Depending upon what purpose and role waveaudio is to play within 
an application, due consideration to all three questions above should be made. 
For instance, an application may require only a minimal amount of disk space 
for executables, but require magnitudes more to store all the data files. Part of 
our purpose here is to provide enough insight into what can be done to strike 
an acceptable balance between the two extremes mentioned before. This bal¬ 
ance will enable an application to be more entertaining, more understandable, 
and more productive. However, before we can go into the specifics of waveaudio 
support within MMPM/2, we must discuss what waveaudio itself is. 


WHAT IS WAVEFORM AUDIO? 


Consider for a moment: What is sound? Although most people who can hear 
take it for granted, the common definition is, simply stated, the effect caused 
by air waves vibrating against the eardrum, hence the term “WAVEaudio,” 
because waves of air are what comprise what we hear. Although this is not 
where the phrase gets its origin, in the context in which we are using it, this 
definition most definitely applies. 

Sound, as interpreted by human hearing (the sounds of a door slamming, a 
cat purring), is the effect of these air vibrations which cause a signal to go the 
brain. The brain then associates events or things with what caused the vibra¬ 
tions. All of the human senses are inter-associated, and hearing is the second 
most important sensory function next to sight. Sounds caused by events in the 
world around us are referred to as analog audio, because the sound the human 
ear detects is for all intents, analogous to the actual waves of air vibrating 
against the eardrum. Therefore, the human ear can be considered an analog 
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device in the sense we refer to devices because every variation in the frequency 
and content of a sound will cause a slight difference in the way the eardrum 
resonates. Thus, for each sound, a unique type of signal is sent to the brain 
from the ear via the auditory nerve. 

Take the example of playing the same musical note on two different instru¬ 
ments: middle C on a trombone sounds somewhat different than the same note 
played on a trumpet. One of the less obvious reasons for this is that each 
instrument, while designed to generate the same tone for the same note on the 
musical scale, have a “personality” all their own. Specifically, because of the 
way the air is compressed to generate the sound. The frequency of sound waves 
(consider the representation of the effect of creating a sound as creating a wave 
of air which carries the sound) is denoted by a standard unit of measure called 
Hertz. Hertz refers to the cycles per second, or the number of rises and falls at 
which a sound wave resonates. Aural acuity varies from person to person. Most 
people hear within the range just above 100Hz to upwards of 20000Hz, 
although some people can hear the hum of electrical transformers which gener¬ 
ate a 60Hz noise. The whole concept of computer waveaudio centers around 
this one basic piece of information, the range of human hearing. 

In contrast to the way human hearing works, computers are considered digi¬ 
tal devices because they can only deal with at the most basic level with binary 
information. Because they utilize quantitative representations^.e., Os or Is) to 
represent any information they manipulate, to truly recreate a sound in the 
same manner as human hearing would require an enormous amount of pro¬ 
cessing power, and, perhaps more importantly, voluminous amounts of storage 
space to maintain. When a sound card records, the sound of a bird chirping, for 
instance, the data actually stored is really only an approximate representation 
of the true sound that was being recorded (Figure 1). The process of converting 
a sound to a digital form is called sampling. The frequency, or number of 
times, a sample is taken within a fixed time period is referred to as the sam¬ 
pling rate. This fixed time period refers to the time elapsed in one second. In 
other words, a sampling rate of 8000 will mean 8000 samples per second. 

Analog Signal to Digital Data Relationship 

In the previous section we stated that the digital representation of an audio 
wave is only an approximation. Here is why. When your sound card samples a 
sound, it is dealing with what’s referred to as an analog signal. The sound is 
converted to a numerical representation of the magnitude in signal that is pre¬ 
sent at the instant the sample is taken. This is represented by the gray bars in 
the graph on the next page. Each one of the bars represents how the digital 
representation of the audio signal at the instant the sample was taken, would 
look like. To be able to recreate the sound faithfully, there must be some level 
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of quantization where there are enough individual samples of the audio signal 
to recreate the original sound. Research into this subject was done in the late 
1920s, by H. Nyquist. His research determined that if an analog audio signal 
were sampled at approximately twice the frequency, or rate, of that signal, 
that sufficient information would be acquired to adequately represent the true 
signal itself. If we were to look at the process of sampling from a simple point 
of view, we could very easily arrive at the conclusion that sampling wave audio 
that records at the highest rate possible would not only be adequate for all 
recordings, but would be the only necessary course of action. Wrong! 



Figure 5-1. Signal Voltage vs. Samples 


Recording frequencies above the range of human hearing, (about 20000Hz, 
or 20Khz, or Kilohertz for each 1000Hz, and above) generates false informa¬ 
tion, or signal aliasing. This corrupts the data which is generated. To eliminate 
this aliasing, a hardware low-pass filter is used and is common in all sound 
cards available today. This filter is basically a method whereby the high-fre¬ 
quency content of an audio signal is stripped and the lower frequency signals 
are passed through. More than just that; due to physical limitations with such 
filters, a slightly higher sampling rate must be used to compensate for the loss 
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of audio signal information, and sound reflection which occurs as sound 
bounces off a surface and eventually reaches the microphone. This is why, to 
record at the high end of the human audible spectrum (20Khz), recording is 
actually performed at 44.1Khz, so that this overcompensation can be per¬ 
formed. The process of overcompensation is commonly referred to as oversam¬ 
pling. This is, part of the core to Nyquist’s theory; oversampling an audio sig¬ 
nal by a factor of two provides adequate information to faithfully reproduce 
that signal. Although most sound cards today support recording of audio data 
at a rate of 44.1Khz, that does not mean that everyone should just use that 
sampling rate exclusively, and with good reason, as we get into later. 

Audible sounds are individually unique, as described in the example of the 
trombone and the trumpet. More than just the sampling rate itself controls the 
quality of a recording. The samples of audio data are, as they are recorded by a 
sound card are converted into Is or Os, or “bits” of information. The amount of 
these bits, which are used to represent the instantaneous magnitude of the 
analog audio signal, also controls the quality of the representation of the 
sounds being recorded. 

Another development of the late 20th century, is the invention of stereo 
recording. Humans, and some animals, hear in stereo. That is, while sounds 
may be received by one ear or the other, the brain is able to directionally deter¬ 
mine from where the sound originated. The format of stereo audio digital data 
contains two separate “channels” of audio signal within one recording, one 
channel for each ear or side (hence left and right channels). The stereo “effect” 
is recreated by “sequencing” the audio information from the left audio channel 
with that of the right. The same is applicable to audio playback as recording. 
Let's go back to our discussion of sound quality for a bit. 

How the amount of signal from one channel or side of data is varied is called 
balance. Balance can also provide for more control of the data primarily for the 
effect it has on the listener. For instance, you can create the effect of motion by 
controlling where the sound “seems” to come from by moving, or panning, the 
sound from one side of the listener to the other. Because of the way the brain 
interprets sounds, the person listening will perceive motion because of where 
the brain determines the sound is coming from. 

Earlier we asked a question: Is 8-bit good enough? The answer is, it 
depends. Since voltage levels are represented in binary form, we derived that 
there are 256 unique levels that can be ascribed to a sample. A simple equa¬ 
tion, 2 A N, where N is the number of bits per sample, determines the number of 
unique levels possible. It follows that increasing the number of bits per sample 
increases the granularity in the number of voltage levels that can be represent¬ 
ed. So, the wider, or the more bits per sample, or BPS, each sample is taken at, 
the more accurately the original signal can be represented when played back. 
Following this idea, you can recognize that sampling at a data width of 16 BPS 
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(2 A 16 = 65536), you will get a more accurate sample of what you are trying to 
record. The one drawback is that the wider the data samples are, the more 
space on disk and memory, is required to store the samples. 

Data Types, Formats , and Storage 

So far, the type of data we have been discussing is called, PCM (Pulse Coded 
Modulation), or sometimes called Linear PCM , because in this form the data 
recorded is exactly as it has been described in this section. Each sample of data 
is a linearly ordered, digitally-coded representation of the modulation of the 
pulse (or wave) of air that is being recorded. That is about as terse and concise 
a definition as we can give you. There are other data formats whereby PCM 
can be stored, the two more common methods are called u-Law (pronounced 
mu-law) and A-Law PCM. These two forms of waveaudio are similar to PCM 
with the exception that they both apply compression to the audio data. Both 
types are used mainly for recording voice (approximately 8Khz). However, 
PCM is still predominantly the form in which most recording is done, in multi- 
media data production, or authoring, today. These were mentioned, primarily 
to denote that other techniques of audio recording, other than PCM, do exist, 
and if supported by your target hardware, can be employed if the need arose. 

A few paragraphs ago we stated that sampling at the highest rate possible is 
not exactly the best or only way to go. The reason for this is the way audio 
itself is digitally encoded and stored. A digital recording is comprised of sam¬ 
ples, each sample is either 8- or 16-bits (there are other data sampling widths 
but these are the two most common), and recordings are done across time with 
either one or two channels of audio data being sampled. PCs measure data 
storage in bytes, so the equation for calculating how much storage a simple 
recording of audio data for 30 seconds at 22050Khz (more commonly referred 
as 22Khz), at 8-bits, mono (a single audio channel). The frequency at which a 
sample of data taken at, is referred to commonly as SPS, or samples per 
second. 

Bytes of Storage = ((SPS*BPS) / 8 ) * # of Channels * seconds 

Plugging in our example numbers: 

Bytes = ((22050 * 8)/8) * 1 * 30, or 661,500 bytes 

Incredible, isn’t it? The amount of data required to store a half minute of 
audio for any of the common audio data formats is quite shocking. Only until a 
couple of years ago did storage space become affordable enough to handle such 
a demand as multimedia places on a system. Consider the high end of the spec¬ 
trum, to store 1 minute of CD quality audio in stereo is over the capacity of the 
majority of hard disk drives produced, up until just a few years ago (Table 5-1)! 
For this reason, most developers producing multimedia titles today ship their 
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product running directly from a CD-ROM, which has the capacity of 650MB of 
data. The hardware transfer rates of most CD-ROM drives today still hover 
around 300Kb/second, and although, recently, some CD-ROM drives have been 
introduced that transfer at 450Kb/second or above, most of these are out of 
reach of most users’ budgets. 


Sampling Rate 

Bits Per Sample 

Channels 

Storage in Kbytes 

8 Khz 

8 

1 

8 

8 Khz 

8 

2 

16 

8 Khz 

16 

1 

16 

8 Khz 

16 

2 

32 

11 Khz 

8 

1 

11 

11 Khz 

8 

2 

22 

11 Khz 

16 

1 

22 

11 Khz 

16 

2 

44 

22 Khz 

8 

1 

22.05 

22 Khz 

8 

2 

44.1 

22 Khz 

16 

1 

44.1 

22 Khz 

16 

2 

88.2 

44 Khz 

8 

1 

44.1 

44 Khz 

8 

2 

88.2 

44 Khz 

16 

1 

88.2 

44 Khz 

16 

2 

176.4 


Table 5-1. Data storage requirements for 1 second of audio 

This brings us back to a point we were careful to make in the introduction of 
the book. The multimedia authoring process is not necessarily a straightfor¬ 
ward one to begin with, but if you keep a few key things in mind while develop¬ 
ing your software, the process should become smoother. 

Here are some ideas. Consider what type of audio recordings you are going 
to be making use of primarily. Are you recording classical music in an auditori¬ 
um? Are you recording plain conversational speech? What type of effect do you 
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want to give to the user? Do you simply want to present the information; is 
that all that is necessary? Do you need to give the person the feeling of “being 
there”? All this can seem confusing, but here are a few “rules of thumb” to go 
by. One, do not “over-author” your audio data. In other words, do not record at 
44Khz because, “It will give me the most clear recording I can get.” This is 
absolutely not true! The fact is, since digital recording is an approximation, 
what type of audio you are recording is really the gating factor. 

Authoring Concepts: Roll Your Own , or Prepackaged? 

Most conversation speech is performed within the lKhz-5.5Khz range. Let us 
go back to what Nyquist states about audio recording for the moment. To faith¬ 
fully reproduce the original audio signal, it is necessary to record at twice the 
highest frequency of sound you are recording. Well, if the theory holds true, 
and it does, then to faithfully reproduce most conversational speech you should 
be able to record at twice the 5.5Khz high-end, or llKhz, and be pretty confi¬ 
dent that you will get a good representation of what was being spoken. Also, 
consider, that unless there is a real need for more, sampling speech at 8-bits is 
also quite sufficient; sampling at 16-bits is not going to get you a more clear 
recording, to offset the additional data storage requirements. The reason for 
this is that, recording speech in a normal conversational style, is so consistent 
(excluding any background noise) on a person by person basis, that 256 levels 
of audio signal are more than adequate to faithfully reproduce what is being 
recorded. 

What if the locale where I am recording is noisy? Noise filtering is more 
commonly handled by the audio hardware, and you should refer to the hard¬ 
ware noise filtering features of any hardware sound card when purchasing it. 
Obviously one the most important things to consider when purchasing audio 
hardware is the type of filtering provided by the card, as well as it is signal to 
noise ratio, the higher the ratio, the cleaner the sound will be as it is recorded. 
However, not all noise can be filtered, and accommodations should be made 
when authoring to create an as noise-free environment as possible when 
preparing recording. 

One point we have not touched upon is the user. The customers (unless you 
are developing an application for some specific hardware configuration or for 
personal use) will have all sorts and variety of equipment options at their dis¬ 
posal. It only makes sense that the developer takes this factor into account. For 
instance, most sound cards today can play back waveaudio at, 8Khz, 8-bit, 
mono. This may be sufficient for the type of audio you are going to be dealing 
with. But, what if you are going to have to play music from an opera in your 
application? Having a recording at only that sampling rate and quality will 
probably sound quite poor, and unappealing to the listener. This could very 
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well be totally unacceptable to the customer. If everyone had the same type of 
audio hardware setup, multimedia development would be a much simpler mat¬ 
ter. Sadly, this is not the case, so again, we have to go back to compromises. 

To recap: we have covered some audio theory, looked briefly at data storage 
requirements, and taken recording quality into consideration for the develop¬ 
ment of an application. You should have a good idea forming in your mind 
about some things to make a mental note of while authoring data and laying 
out that data for your application. 

Of course, there are many sources of audio content available, to make use of. 
Many companies literally have thousands of sound “bites” available on compact 
disc. There may be circumstances where you may wish to use these types of 
“content-only” media. However, make note that many of these CDs may con¬ 
tain copyrighted material, and if you are using the content from such a CD for 
personal or internal company use, this may not be permitted under the license 
provided by the author. If you wish to employ sounds from these types of CDs 
for a product you are going to market or sell, you should check what limitations 
are placed on the reuse of those sounds, before you buy. Many multimedia soft¬ 
ware developers today can and do use these types of content CDs. As a matter 
of fact, there is a booming business in creating audio and motion video content 
CDs themselves. However, most commercial multimedia developers today sim¬ 
ply create or record their own content, because of two important reasons: 

1. originality; 

2. content quality control. 

If you perform all your own recording and editing, you are assured of the 
quality and originality of your product. 


WHAT PARTS OF MMPM/2 DO I USE? 


We will be using the MCI interface to manipulate the waveaudio device and, 
for most of the samples in the rest of this chapter, we need use only two of the 
MCI APIs: mciSendString and mciSendCommand. These two functions will 
provide most of the functionality necessary to perform most audio playback 
and recording. For each sample, we will use the string interface to demonstrate 
how to perform the command(s). Where there are command keywords, we will 
discuss what the keyword means and what its purpose is. Some examples may 
show a slight variation in the call to illustrate how changing even just one 
parameter can perform something entirely different. 
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AUDIO PLAYBACK 



Figure 5-2. Audio playback / record architecture 

The above illustration may appear quite complex. Yet, while it presents more 
detail about the audio playback process than we can cover in the context of this 
book, it is necessary to have at least some understanding of this process. In 
this illustration (assuming audio playback), we demonstrate a file stored on 
disk, which is read into memory, processed by MMPM/2, and subsequently 
played back by a hardware audio device. 

The internal representation for any data within MMPM/2 is built on the 
concept of streams. A stream of data has at least one source, and one target. In 
this example, the source is the File System Stream Handler (FSSH), and the 
target is the Audio Stream Handler (ADSH). To get the data from the source to 
the target there is the Sync/Stream Manager (SSM), whose job is to manage 
the process of transferring data buffers, handling internal synchronization, 
and generating external synchronization events and notifications. When you 
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open, or load, a data file for the waveaudio device, the Audio Media Driver 
(AUDIOMCD) will perform the appropriate calls to the Multimedia I/O 
Manager (MMIO) to open the file and get information about the format and 
content of the file. 

The AUDIOMCD also internally performs any initialization of the hard¬ 
ware audio device necessary by routing requests to the amplifier/mixer Media 
Driver (AmpMix) device which controls things like volume, and any other 
device specific settings. Then, the AUDIOMCD requests that the SSM create 
an association between source and target stream handlers and creation of a 
stream to be the carrier for the data between the two. Inherent to the stream 
are a list of stream buffers which the source (FSSH) will produce, and the tar¬ 
get (ADSH) will consume. The job of the stream handlers in MMPM/2 is to 
maintain data flow at as close to real-time rate as possible. 

A certain number of buffers (dependent on the specific audio device itself) 
are usually pre-filled (or pre-rolled) to enhance performance of the system. 
When the request is made to play the audio data, the AUDIOMCD requests 
that the SSM initiate the streaming process. At this point, unless there are 
notifications and/or cuepoints involved, the SSM is in control of the process. It 
manages buffers being produced by the FSSH, transferring these buffers to the 
ADSH, which then sends them to the OEM device driver (or VSD, for Vendor 
Specific Driver) for processing by the hardware audio device itself. Once a 
buffer is consumed by the hardware, it is returned back to the SSM for recy¬ 
cling. The SSM internally manages both full and empty buffers and maintains 
a constant supply of buffers for both FSSH and ADSH as long as the stream¬ 
ing process is active. Once there is no more data available from the source (end 
of file), the full buffers are continued to be sent to the ADSH, but the FSSH is 
halted. Once all buffers are consumed by the hardware itself, they are returned 
to the SSM, at which point the ADSH is also halted. 

Briefly, if the roles were reversed for ADSH, and FSSH, the process would 
be one of recording audio data. The ADSH would be sending empty buffers to 
the audio hardware, then returning them to SSM, who would then pass them 
to FSSH for storage. Please note this is a very simple scenario we have pre¬ 
sented here, but our intention was to give you at least some idea of the inner 
workings of playing back waveaudio under MMPM/2. 

Determining What Is Available 

In MMPM/2, there are several ways to play back an audio file. Obviously, the 
simplest way is to utilize the MCI to do this, however, there are several options 
at your disposal. One of things that you immediately need to determine is, “Is 
there a waveaudio device at all?” And, for that matter, “How many of them are 
there?” MMPM/2 supports multiple media devices of the same type, and it is 
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always a good idea to determine just how many are there. For example, it is 
possible to have SoundBlaster® Pro and ProAudio® Spectrum 16 cards present 
in the system at the same time. Since it is possible to have more than one 
audio card installed, you might want to consider supporting one or all of those 
cards present. 

To determine how many waveaudio devices are present in the system it is 
simplest to call mciSendString , such as: 


ulRC = mciSendString(“sysinfo waveaudio quantity wait”, pszNumAudio, 
strlen(pszNumAudio), hWnd, OL ); 


The number of the waveaudio devices present in the system will be 
returned by the MCI, in the string, pszNumAudio. This same request can be 
used with other device types to determine how many of those devices are pre¬ 
sent. One advantage of this command is that it is handled directly by the MDM 
with no intervention by any media driver, and that the call returns almost 
immediately. 

It is possible to determine the same thing in a different manner. If a number 
is appended at the end of name of the device, and then an open command was 
sent to the MCI (in this example, waveaudio would become waveaudioxx, 
replacing “xx” with a two digit decimal number). For instance, selecting 
waveaudioOl would be equivalent to selecting the first, and not necessarily 
the default, audio device in the system. This method is not something that we 
really advise that applications make use of, as it opens an instance for each 
and every device, of the type you are opening, in the system. 

Opening the Waveaudio Device 

Since there are a variety of methods to open the waveaudio device, the varia¬ 
tions can become quite confusing. Here is a rather simple form of opening the 
waveaudio device: 


char szCommandl[80] = “open waveaudio alias wavel shareable wait”; 
char szCommand2[80] = “open tut.wav alias wavel shareable wait”; 
char pszReturn[MCI_RETURN_STRING_LEN]; /* Define length as you wish */ 

ULONG ulRC; 


ulRC = mciSendString((PSZ) szCommandX, (PSZ)pszReturn, 
MCI_RETURN_STRING_LEN, NULL, 0 ); 

/* replace szCommandX with either one of the strings above */ 
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Both of the example strings (szCommandl or szCommand2) will try to open 
a waveaudio device, and verify that they had a successful open of the device 
by checking the return code. If MCIERRJSUCCESS is returned in the return 
code (ulRC), then you know that there is at least one waveaudio device pre¬ 
sent in the system, and that you have an instance of this device available to 
you. 

The first string attempts to open the default waveaudio device. Remember 
from the Using the Media Control Device Interface chapter that there is a 
default device setup for each device type. To open the default device the device 
type name is used without any ordinal or number appended to it. If there are 
more than one device of the same type in the system, then this becomes impor¬ 
tant to the user and to applications. The default device can be changed by the 
user by using the Setup applet. 

Notice that the second string (szCommand2 ) omitted explicitly stating the 
device type that we wished to have opened. This is because when MMPM/2 is 
installed, there are several file type <—> device associations which are created. 
They are set up so that when a fully qualified filename (i.e., one including the 
extension of the file) is specified, the system will automatically attempt to 
determine which device is necessary to handle the type of data element you 
provided as the element (or file) name and open that device. Based on the 
extension of file element specified (.WAV, .MID, etc.), MMPM/2 will open that 
device that has the association set. 

If no extension <—> device association exists for the given file extension 
then MMPM/2 will go query the EA, or Extended Attributes, information 
associated with that file, and determine from there which device is necessary. 
This all happens internally, and if you are not interested either in keeping in 
mind which device you open, or of what type a given file is, then simply per¬ 
form the open with only the element name specified, and no device type. 

There is one final way to open a particular device with a file element. This 
case is in a sense a combination of the two samples we have just presented. To 
open a particular waveaudio device and use a file element on the open do the 
following: 


char szCommand[80] = ‘‘open tut.wav type waveaudio02 alias wavel 
shareable wait”; 

char pszReturn[MCI_RETURN_STRING_LEN]; /* Define as you wish */ 
ULONG ulRC; 


ulRC = mciSendString((PSZ) szCommand, (PSZ)pszReturn, 

MCI_RETURN_STRING_LEN, NULL, 0 ); 
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The type keyword overrides MDM searching for a device to open based on 
the file extension or EA association. 

Before going any further, it is very important to note that opens requests 
require both CPU and system resource. A good application design should take 
into account that opens be performed only as necessary, and as infrequently as 
possible. If your application requires use of more than one device, open 
instances only for those you require presently. We talk more about this when 
we discuss the load command. 


OPEN MODES AND DEVICE OWNERSHIP 


In the chapter on MCI, in the section describing the open command, we 
describe several sharing modes that the device could be opened in. In the open 
example we show here, the device was opened in shareable mode. This mode 
is probably the most preferred mode for simple playback of audio within 
MMPM/2, because it is the mode that is most cooperative with other applica¬ 
tion, and with MMPM/2 system sounds. When an application opens a device in 
this sharing mode, it must be prepared to handle the MM_MCIPASSDEVTCE 
message, and it must make all adjustments necessary internally to deal with 
acquisition/relinquishing of ownership of a device instance. The MM_MCI- 
PASSDEVICE message is discussed in more detail in the Resource 
Management section in Chapter 3. The two commands for handling acquisition 
and relinquishing of device ownership are acquire and release. Here are two 
examples which would apply to the form of open that we used in the previous 
example: 


char pszReturn[MCI_RETURN_STRING_LEN]; /* Define as you wish */ 
ULONG ulRC; 

HWND hWndNotify=hWndHandler; 


/* If we need the device and send an ACQUIRE....*/ 

ulRC = mciSendString((PSZ) “acquire wavel wait”, 

(PSZ)szReturn, 

MCI_RETURN_STRING_LEN , hWndNotify, 0 ); 


or 


/* If we are going to release a device */ 


ulRC = mciSendString((PSZ)”release wavel return resource wait”, 
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(PSZ)pszReturn, 

MCI_RETURN_STRING_LEN ,hWndNotify, 0 ); 


/* 

In our Window Procedure we handle the MM_MCIPASSDEVICE message 
accordingly. 

*/ 


case MM_MClPASSDEVICE: 

switch ( SH0RTlFR0MMP(mp2) ) 

{ 

case MCI_GAINING_USE: 

bOwnerShip = TRUE; 

/* Application specific handling */ 
break; 

case MCI_LOSING_USE: 

bOwnerShip = FALSE; 

/* Application specific handling */ 
break; 

} 


break; 


This gives us a brief idea of what happens with both the acquire and 
release commands. 

If the device were to be opened with the exclusive keyword instead of the 
shareable keyword, then the device will be assured of one important thing: 
the device instance will never be made inactive. This is the mode that applica¬ 
tions should use to open the device when they do not want the device instance 
to be made inactive. Although this mode provides the most protection for appli¬ 
cations, it should really be avoided because it requires the most resources from 
the system. 

Device IDs 

Even if you open a device without specifying a specific device name, it is possi¬ 
ble to determine which device was indeed opened. The previous example asks 
the MCI to return to you an instance of the default audio device present in the 
system, and a device ID is returned in the pszReturn string. This string must 
be converted to a value to be used in any subsequent calls to MCI which utilize 
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a device ID. Remember that the device ID is required for most 
mciSendCommand API calls. Another method to acquire that device ID is by 
calling mciGetDevicelD as follows: 


usDevicelD = (USHORT)meiGetDeviceID( (PSZ)“wavel”); 


Because we have specified an alias for the waveaudio device that we were 
opening, we can get the ID for the device by specifying that alias when calling 
mciGetDevicelD , in this example. This also means we could have omitted pro¬ 
viding the pszReturn and MCIJRETURN_STRING_LEN parameters in the 
previous few open examples. If the string supplied equates to a known open 
device instance, the ID will be returned in usDevicelD. This value can then 
be used wherever a device ID is necessary. However, the device ID is used 
almost exclusively by the mciSendCommand API, while we present our 
examples using the simpler string interface imciSendString). Having this 
device ID will be useful when receiving messages to determine to which device 
the message referred. After all, an application can have more than one device 
or device instance open at a time, if the media driver supports multiple 
instances. 

Device Capabilities 

Given that one of our open examples opened a data element without specifying 
the device type, what type was opened can be easily determined by performing 
a capability request with the device type keyword. 


capability wavel device type wait” 


The capability command can be used to query a variety of information from 
a media device. To determine specific device capabilities there are several data 
format parameters to the capability command. Several waveaudio specific 
format capabilities are listed in Table 5-2. Here is an example of querying 
whether the device is capable of supporting a specific audio playback or record 
configuration: 


“capability wavel extended format bitspersample 16 
samplespersec 22050 channels 1 tag pem wait” 
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This call will return “true” or “false” in pszReturn , to indicate whether the 
device is capable of the supporting the data format that was requested. Here 
are some of the extended capabilities which should be supported by most audio 
drivers: 


Format 

Type 

bitspersample 

8 or 16 

samplespersec 

Any decimal number 

channels 

1 or 2 for Mono or Stereo 

tag 

see audio compression section 

mode 

play or record 


Table 5-2. Waveaudio device capability format strings 


These format capabilities are most important when the application needs to 
make use of a specific audio data format, to make sure the audio device can 
support the playback (or record) in that format. The tag keyword refers to the 
audio storage and compression formats supported by MMPM/2. This subject is 
discussed later in the chapter, under the Audio Compression Types section. 
The capability extended format command, must follow the format specified 
in the example, because the hardware device will be queried directly. If, for 
instance, you wish to record at 44.1Khz, a Sound Blaster Pro will be able to 
record at the frequency with only 8-bits per sample, mono mode. The Sound 
Blaster 16, on the other hand, will be able to record at 44.1Khz, at both 8- and 
16-bits per sample, and both mono and stereo modes. Notice the difference in 
capabilities. Without having to deal with the specifics of what card is being 
used by MMPM/2, the developer should determine whether a specific mode set¬ 
ting is supported by MMPM/2. Before changing a setting, it should be deter¬ 
mined if changing that setting, given other mode parameters that might be set, 
will work. It is always possible to go ahead and make the request to change the 
setting, and to deal with an error response, but we do not recommend that 
development be done this way. 

Here is a list of some of the type definitions for audio related hardware: 

• MCI_DEVTYPE_WAVEFORM_AUDIO 

• MCIJDEVTYPE.SEQUENCER 

• MCI_DEVTYPE_AUDIO_AMPMIX 

• MCI_DEVTYPE_SPEAKER 
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• MCI_DEVTYPE_HEADPHONE 

• MCI_DEVTYPE_MICROPHONE 

Obviously there are more device types supported by MMPM/2, however, 
these are the device types most associated with waveaudio. The three most 
common are waveform audio, sequencer, and audio ampmixer (or ampmix, for 
short). These two other devices (sequencer, and ampmix) refer to the devices 
which support MIDI (sequencer) and Amplifier/Audio Mixer (ampmix). These 
other devices will be discussed later in the chapter. 


Loading Audio Files 

In the open example, we loaded the data file we wished to use as a parameter 
of the open. While there may be instances where this is all that is necessary, 
our advice is that unless you DO NOT have a specific “data element” to use, 
that you open the device without one. However, if you do not have a data file to 
use upon opening the device, open it without one. Keep in mind that this caus¬ 
es the device to be initiated in whatever state the hardware device starts up in. 
Normally this mode is record mode. When you load a data file this may require 
all sorts of changes to the configuration of the device, all during the load, and 
thus inhibiting good performance. Then, you can load in the waveaudio file 
you wish to play something back by issuing a load command: 


char szCommand[255]= “load 
char szFi1e[25]; 

char pszReturn[MCI_RETURN_STRING_LEN]; /* Define as you wish */ 
ULONG ulRC; 


strcpy( szFile, “tut.wav” ); 

sprintf( szCommand, “%s %s”, szFile, “wait” ); 

ulRC = mciSendString( (PSZ) szCommand, (PSZ)pszReturn, 
MCI_RETURN_STRING_LEN, ,NULL,0 ); 


The load command causes MMPM/2 to actually open the data file, read in 
the Resource Interchange File Format, or RIFF, header information, set up 
the media device with the all the information (samples per second, bits per 
sample, etc.) regarding the data file, allocate streaming buffers, and prime 
some of the data for playback. Essentially, you can consider the load command 
as having the distinction of performing the “grunt” work of preparing to play a 
data file. Remember, if you opened the device without specifying a file, or ele¬ 
ment to load, only part of the processing has been performed. Before we go any 
further, a point we have to emphasize here, which is covered in more detail in 




Audio Playback and Record 191 


the performance chapter, is that as a developer, you make choices every day 
about how you organize your application and where and when you perform cer¬ 
tain operations, and why. The relationship between open and load is just such 
an instance. In this instance due consideration is given not to just what, but 
also to where certain things are done to give your application the best perfor¬ 
mance possible. Another consideration is whether all the application is ever 
going to do is to play back audio files if the device and or data is opened in 
read-only mode. This will help your overall performance. When a file is loaded 
in the default fashion by the MCI, MMIO, which handles all I/O requests, will 
open the file in Read-Write mode. Additionally, due to the design of MMIO, 
which must handle requests for information which may not even be on disk 
yet, under certain circumstances, MMIO must create temporary “working” files 
that it will use whenever necessary. The readonly keyword is simply added to 
the keywords specified in the command string for an open or load command: 


“load tut.wav readonly wait” 


Note also that the open and load commands of MCI do not have such 
diverse modes of operation for nothing. Consider the example of a simple file¬ 
name; these other types of data elements can be specified in its place: 


Data Element Type 

Sample Element 

Resultant Action 

Compound File 

“Sample.bnd” 

The compound file is opened 
and it’s TOC is scanned in. 

File & Element 

“Sample.bnd+birdy” 

Compound file is opened and 
element “birdy” is loaded. 

HMMIO 

(PSZ)mmioHnd 

MCI will utilize the handle as 
the handle source for the audio 
data. 


Table 5-3. Audio open types 

Another good point to remember is to try to utilize as like data files as possi¬ 
ble. In other words, if you decide that 22Khz, 8-bit, mono is adequate for your 
needs, then make certain all your data files are in this format. This greatly 
improves performance when loading a new file into the system because the 
streaming buffers that were created for the previous data file will be recycled 
and reused. If the new data file has the same characteristics as the currently- 
loaded file, then the new file is simply associated with the current audio 
stream. This is the most efficient method for loading a file. Lastly, if you so 
wish, you can open the data file yourself, query information, etc., and then, 
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when necessary, perform the load command and pass in the handle returned 
by MMIO as the data element to load. This also improves overall performance 
of the system. The MMIO handle can not be use on the string interface, it must 
be used with the mciSendCommand API. 


Cue 


If the load command has succeeded, MMPM/2 is now prepared to play your 
data file. Assuming at that point you wish to play it back, you have an active 
instance of the device. Note, however, that unless you are going to play back 
the file immediately, it might be wise to “cue the tape,” so to speak. For 
instance, if your application were allowed for voice annotation along with the 
text for a letter, when you are loading the text for the reader to view, also cue 
the audio, so that when the reader selects to have the annotation played back, 
the audio can begin almost immediately. The point is that even if the file has 
been loaded, there is a certain amount of work associated with cueing, or pre¬ 
rolling (the two phrases are interchangeable), the device with the audio data. 
Here is how to go about cueing your audio: 


“cue wavel outout wait” 


Now the waveaudio device is cued to immediately start playing back audio. 
This means that the necessary audio buffers have been filled and the audio 
stream is ready for playback. 

Playing Audio 

Now that we have the device open and the data is loaded and cued, we can play 
the audio whenever we wish. Here is an example of how to play your waveau¬ 
dio data synchronously: 


char szCommandPlaySimple[80] = “play wavel wait”; 
char szCommandPlayFromTo[80]; 

char pszReturn[MCI_RETURN_STRING_LEN]; /* Define as you wish */ 

ulRC = mciSendString( (PSZ) szCommandPlaySimple, (PSZ)pszReturn, 

MCI_RETURN_STRING_LEN .NULL, 0 ); 


or 
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sprintf(szCommandPlayFromTo, “play %s from %l to %I %s”, 

“wavel”, 1000, 5000, “wait” ); 

ulRC = mciSendString( (PSZ) szCommandPlayFromTo, (PSZ)pszReturn, 

MCI_RETURN_STRING_LEN , NULL, 0 ); 


In the first play example, we requested a very basic form of the play com¬ 
mand which instructs MCI to play the waveform audio file until it is finished. 
This points out another one of the instances where a multitasking environment 
can either become a blessing or a curse. Looking at the command string, notice 
that we used the wait keyword. The logic in MCI is being told to perform this 
operation synchronously. If you issue this form of the command from within a 
PM window procedure, the application would effectively halt, or hold, process¬ 
ing of any messages sent by the system, and could appear to the user as though 
the application were “hung” (colloquialism for an application that does not 
respond to system or user input). 

Since OS/2 is a multitasking operating system, you can play a waveform 
audio file in a variety of ways. So far, we have only referred to playing audio in 
a synchronous fashion. The other way is to play it asynchronously. This can be 
performed in two ways. The first is to use MCI notification facilities exclusive¬ 
ly, and allow the system to let you know when things are done or completed. 
This model suits more a single-tasking or cooperative multitasking model like 
Windows. 

To really take advantage of OS/2’s and MMPM/2’s features, it might be wise 
to use the same rule of thumb applied to programming OS/2 PM itself. 
Disassociate processing of multimedia commands from the user-interface and 
from other functions within your application. That is, perform your multimedia 
operations in a separate thread, and utilize some sort of messaging between 
your main application and the thread that handles MMPM/2. This model fol¬ 
lows the strategy of client/server program design, and not only provides more 
overall program stability, but for manageability of the code itself. Whether you 
wish to wait for an operation to finish synchronously, or to be notified asyn¬ 
chronously and still remain responsive to the user and the system, here are 
two rules to follow: 

1. Issue MCI commands from a secondary or background thread. 

2. Utilize the keyword notify in your commands and serialize access to mul¬ 
timedia components via semaphore, or similar mechanism. 

The first rule indicates that you should create a separate thread, and use 
whatever mechanism you wish to communicate to the thread what the com¬ 
mand is. Then have the function(s) running within that thread perform all the 
interaction with MMPM/2. This is like the client-server model we discussed 
before. The most common way this is done for PM applications that must have 
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“background” processing is to have an object window created within the other 
thread, and post messages from one window to another. Thus, the main appli¬ 
cation window becomes a client of the object window, which subsequently, han¬ 
dles all interaction with MMPM/2 itself. It is possible that using this method 
could cause your application to incur some lag time from the moment you post 
the request to when the request is actually processed. However, unless the sys¬ 
tem is heavily loaded, this time “hit” will probably be minor. 

The second rule is much simpler to use and implement, if you remember one 
word; serialization. Serialization can be performed by having a mutex sema¬ 
phore that is set when the call is made to play the data file, you must also spec¬ 
ify the notify flag with that call. Then, when the window receives the 
MM_MCINOTIFY message, the window can then clear the mutex, and allow 
access to the device again. Obviously, all the functions where you access the 
waveaudio device should follow this same procedure. 

In the second form of the play example, the command is presented, with one 
variation from the first. We set the from and to keywords for the command. 
The from to 1000, which indicates that we want audio to begin from a specific 
point within the audio data (assume 1000 means 1000 milliseconds in this 
example). We also told MCI to stop at 5000 by specifying to in the string. This 
gives you the flexibility and control to specify down to explicitly where you 
want a particular operation to take place from (the from and to keywords 
apply to several different commands in MCI). We, however, made no mention 
as to what time format MMPM/2, or the application for that matter, was using. 
The next section discusses how to determine what time format is currently set, 
what some time formats available are, and how to set them yourself. 

Time Formats and Tracking Playback 

So far, we have been able to open an audio device, load a file into it, and play 
from the device, but now, we should look at how to take advantage of some 
more of MMPM/2 functionality. You may want to synchronize the audio with 
an event of something you wish to display on the screen, or vice-versa. 

How is this accomplished? One of the most powerful features of MMPM/2 is 
the ability to provide synchronization for applications via timing events. 
Timing events can be either periodic or single instanced. These two types can 
be done via setpositionadvise and setcuepoint commands. These commands 
were discussed in the Using the Media Control Interface chapter but, they bear 
some further elaboration. The best thing about these two mechanisms is that 
all the work is being performed by MMPM/2 internally. That way applications 
can concentrate on what they want to do once that “event” occurs, and not 
tracking getting there. 
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If you wanted to have a running indicator of where a playback operation is 
currently, you could cause a MM__MCIPOSITIONCHANGE message to be 
sent to a slider, or to a static window which would either show the point along 
the time path of the data you were at, as a running “chronograph.” To set an 
interval to be notified at every second, send the following command: 


“setpositionadvise wavel on every 1000 return 1000 notify” 


This way you can create a visual cue for the user of how far along you are in 
the data. Notice the numbers we used to denote the time interval. The “1000” 
could mean almost anything. That is because, as with the example before this 
one, we did not specifically set the time format for the device. The default time 
format for MMPM/2 is MMTIME, which is 1/3000 of a second. If we substitute 
our number (1000) for the one (1) in the MMTIME format, we come up with 
1000/3000 or 1/3 of a second, not exactly what we had in mind originally. 
Therefore, you should always set the time format ahead of time, prior to the 
first operation, before playing the audio data. Here are some common time for¬ 
mats available in MMPM/2: 


Time Format 

Devices Supported 

MMTIME 

All audio devices 

milliseconds 

Waveaudio, Sequencer 

bytes 

Waveaudio 

samples 

Waveaudio 

SMPTE 

Sequencer 

song pointer 

Sequencer 


Figure 5-3. Audio-related time formats 
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There are other time formats available in MMPM/2, but the ones in this list 
refers just to those supported by audio devices. Setting the time format is 
accomplished by using the MCI set command: 


“set wavel time format milliseconds wait” 

/* or, to determine the current time format, use: */ 
“status wavel time format wait” 


The first command sets the time format for the device to milliseconds. 
The second command string queries the time format that the device is cur¬ 
rently using. Using the setpositionadvise command from the previous exam¬ 
ple will then get us notification once every second which is exactly what we 
wanted. However, it should be noted that when the notification to the callback 
window occurs, the time position returned in the second parameter ( mp2 ) to 
that callback handle will be strictly in MMTIME units. Even though you speci¬ 
fy a notification time in a different format, you should still account for that fact 
notification is returned in MMTIME format within your application. This is 
because the application can change the device instance’s time format at any 
time. Trying to match the MM_MCIPOSITIONCHANGE message time to the 
time format that was current when the setpositionadvise message was 
issued is a problem. MMPM/2 has a set of macros for converting to and from 
MMTIME and other time formats. These macros are contain in the MCIOS2.H 
header file. Here are the two most commonly used for waveaudio related work: 


Macro name 

Conversion performed 

MSECTOMM (value) 

Converts Milliseconds to MMTIME 

MSECFROMM(value) 

Converts MMTIME to Milliseconds 


Table 5-4. Time format conversion macros 


While setpositionadvise notifies us every time a certain amount of time 
has elapsed, if you wanted to set only a specific moment during playback to 
which you wanted a notification, the setcuepoint command should be sent to 
the device. Here is how to perform a setcuepoint command: 


setcuepoint wavel on at 5000 return 1 wait 
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This sets a cuepoint event to occur at the moment playback of the audio data 
reaches 5000 milliseconds, or 5 seconds. Notice that 1 was used with the 
return keyword in this command. This is one possible way not to have to deal 
with the fact that notifications are returned in MMTXME, and not in the time 
format you have set the device to. Where the 1 was specified as the return 
value in the example, you can denote a cuepoint number, or index. In other 
words, it denotes which cuepoint this cuepoint is. That way, when the 
MM_MCICUEPOINT message is sent to the window, it can act upon it in con¬ 
text of which cuepoint was reported. At this point, the application can use that 
to denote which course of action to take. Notice that we provide a window han¬ 
dle in both the setpositionadvise and setcuepoint commands. The handle 
you provide the MCI must be a valid window handle, although different cue- 
points may be directed at any window you choose. Also, a good thing to keep in 
mind is that the number of active cuepoints per device varies, but a good base¬ 
line default number would be twenty (20). 


Seeking 


Although so far we’ve demonstrated that for the play command it is possible to 
specify from what position to play back the audio from, it should be noted that 
it is possible to set the current media position manually. This is performed via 
the seek command. For instance: 


“Seek wavel to 1500 wait” 


This sample moves the current media position to the particular point speci¬ 
fied by the to. The number specified, again, as before, is specific to the time 
format the device is currently set to use. It is possible to reposition the media 
position at any time desired, as long as one thing is noted: seeking during a 
playback or record operation will cause the device to stop prior to performing 
the repositioning. After a seek command it is a good ideal to issue a cue com¬ 
mand to preroll the device for playback. The keywords to start and to end can 
be used to seek to the start of the media and the end of the media respectively. 
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Pause , Resume and Stop 

While playing back audio, the user may choose to stop or pause the playback of 
the audio. While the syntax of the pause and stop commands are identical, 
there is a vast difference in what effect these two commands have on the 
system. 


“pause wavel wait”,(PSZ)szReturn 
“stop wavel wait”,(PSZ)szReturn 


The stop will cause all streaming buffers to be flushed from the stream han¬ 
dlers, and all of them will be considered to be empty and reusable. The stream 
handlers are returned to an inactive state. To continue playback, a play would 
cause these buffers to be reinitialized, just as if this were the first time the 
audio was being played back. The position of the media will remain at its cur¬ 
rent position. Pause, however, will only cause the stream handlers to become 
inactive, and the stream buffers will remain behind in the current state they 
were in when the command was received. Playback can be resumed via the 
resume command: 


“resume wavel notify 


The resume will initiate playback from the current media position. It 
should seem apparent that pause and resume will provide better performance 
and control of playback. These commands behave in a very similar manner for 
recording as they do for playback, with the exception that stop does not cause 
buffers that have already been stored by the FSSH to be lost. Only those that 
the vendor-specific driver currently had received back from audio device driver 
would be lost. 


Volume 


When the waveaudio device is opened initially, the device has a default 
setting for its volume. Before playback, the application should query what 
the current volume setting is, and if so desired, display it and allow its 
modification. 
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/* Query */ 

ulRC = mciSendString(“status wavel volume wait”,(PSZ)szReturn, 

strlen(szReturn) .NULL, 0 ); 

usVolume = atoi(pszReturn); /* Retrieve Volume setting */ 


/* SET */ 

ulRC = mciSendString(“set wavel volume 50 wait”,(PSZ)szReturn, 

strlen(szReturn) .NULL, 0 ); 


The first example queries the waveaudio device for the current volume set¬ 
ting. This setting will be returned in the string, pszReturn. The second sets the 
volume to the value of 50. As noted in the Using the Media Control Interface 
chapter, the changing of the volume can be done over some period of time by 
using the delay flag and a delay time. 

Media Position 

In discussing the seek command, we mentioned something called the media 
position. MMPM/2 always knows where along in the data stream, its current 
position is. To determine where this media position is use the status 
command: 


“status wavel position wait” 


The value returned will be the current media position in the current time 
format. 


SIMPLE AUDIO PLAYBACK 


We have discussed how to playback audio files with complete control over the 
setup and playback. MMPM/2 provides two very simple-to-use playback APIs 
that do not require any application control or setup. These APIs are 
mciPlayFile and mciPlayRe source. These APIs allow applications to play¬ 
back audio files. The mciPlayFile API specifies that file name as one of its 
parameters and the mciPlayResource API has the file name as part of a 
resource file. To us the mciPlayFile interface issue the following: 
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ULONG ulRC; 

ulRC = mciPI ay Fi1e(hWnd, “bells.wav”, 0, 0, 0); 


The parameters for these two APIs are discussed in more detail in the Using 
the Media Control Interface and Appendix chapters. 


RECORDING AUDIO 


Recording any piece of sound it is possible to do in the same manner as with 
playback. Opening the device, setting it up with a few parameters, starting the 
process or recording, and then stopping it when the user clicks on a button in a 
dialog. If your intent, instead of recording audio content, is to provide the user 
with a simple annotation facility from within your application, the work has 
already been done for you! The mciRecordAudioFileO API records at llKhz, 
mono PCM audio, which is perfect for providing a facility to let the user record 
little reminders to themselves or to tack on a message in a piece of mail to a 
friend or associate, to name just a few examples. 


/* Include OS/2 and MMPM/2 headers */ 

ULONG ulRC; 

ulRC = mciRecordAudioFi1e(hWnd, “Note.wav,” “NoteTaker/2,” 0); 


The above example, requests that a small recorder window be presented to 
the user, whereby they can initiate the record at will, stop it, and save back the 
annotation. The recording will be written to the file name provided in the sec¬ 
ond parameter. The window handle is necessary so that normal PM message 
processing can continue to be fluid. The mciRecordAudioFile API is nice 
since it is object-oriented in the way it works, and it is simple enough to handle 
many jobs of recording audio data from within an application. On the other 
hand, this API is severely limited. Remember, you can only record at llkhz, 
mono, PCM, and for many instances, that is simply not enough. Next, we look 
at how to do more detailed controlled recording. 

In the previous section, we presented an example of how to open the 
waveaudio device in an undirected manner, that is, we simply ask MMPM/2 
to “give it to us.” We make no specific request as to a data element to use, or 
how to prepare itself to do what we want. If we open the audio device in that 
manner, the default behavior of the waveaudio device is to be in record 
mode, because, logically, if we specify no file on which to operate, the only 
other alternative must be that we are going to record something into the 
device. If this is case, then we are already half way towards our goal in this 
section: recording audio. 
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Once the device is open, there may be no specific mode that the device is in. 
Therefore, no assumption should be made about this, and you should query 
this information yourself. Of course, if you do not care, then you go about set¬ 
ting the mode you wish to use whenever necessary. However, if you wish to 
know about what mode the device is set to when you open it do the following: 


ulRC = mciSendString(“status wavel samplespersec wait”, 

pszReturn, 

(PSZ)szReturn,strlen(szReturn) ,NULL, 0 ); 
usSamplePerSec = atoi( pszReturn ); 


This example, the samplespersec can be replaced by the following strings 
to return other format status. 


String 

Mode 

bitspersample 

8- or 16-bit 

bytespersec 

bytes per second 

channels 

mono or stereo 

samplespersec 

samples per second 

format tag 

see audio compression section 


Table 5-5. Status format strings 

Other settings might apply (blockalign, etc.), and all requests can be done 
in the same manner as shown, but the ones in the table are the most pertinent 
to normal usage of waveaudio. 

Now that we have found out what mode the device is set to record in, if the 
mode is not what you want to use, then by replacing the status command with 
a set, in the command string the device can be placed into whatever supported 
mode you wish to use. However, you may not know what modes are supported 
by the audio device you have. The system may have two audio devices, only one 
of which may support the mode you need. 

How do find out which ones are supported? Good question. First, consider 
the following table: 
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Samples Per Second 

Bits Per Sample 

Channels 

8 Khz 

8/16 

M/S 

11 Khz 

8/16 

M/S 

22.05 Khz 

8/16 

M/S 

44.1 Khz 

8/16 

M/S 


This table lists the standard PCM data record and playback rates and 
modes supported by the vast majority of audio hardware available today. 
Wherever you see (8/16), it refers to both 8- and 16-bits per sample, and (M/S) 
refer to both mono and stereo formats. So, now that we have a little better pic¬ 
ture of what most hardware supports we can weigh our options. Earlier in the 
chapter, we mention that to record normal conversational speech only about 
8Khz, 8bps (or bits per sample), mono was really necessary. The truth is that 
the recording process is quite possibly most tediously painful and downright 
aggravating processes you may have to go through. Consider that even with all 
the technology at their disposal today, most editors for and mixers for even the 
smallest record label will take weeks, even months just to perfect the sound to 
the way they want it. No one can become a Stradivarius overnight in creating 
recordings, it is a process learned by trial and error. However, our task is to 
give some simple insight to help get you started. Consider: 

1. The source of the recording. 

2. The environment in which you are recording. 

3. The type of audience to which the recording will be presented. 

4. The media where the recording will be stored. 

These four are the most basic concerns in the audio recording process. All 
professional musicians, whether procedurally or as second nature, use all four 
of these considerations to produce the music published today. In a sense, if you 
are authoring audio resources for your application, are a music publisher, and 
while you may try to, you will not be able to avoid them totally. 

Audio Compression Types 

In Table 5-6 where we displayed the commands keywords for determining 
what sampling rate, BPS, and number of channels the audio file had, we men¬ 
tioned, but we did not go into, what is referred to as format tag. The format 
tag refers to the storage method for what form the data itself is lain out. In 
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other words, how are the bytes of data for the recording stored in memory or 
on disk? The following table presents a list of some of the more common format 
tags available for use in recording: 


Format Tag 

String Command 

Format 

PCM 

pcm 

Linear PCM 

IBM_CVSD 

cvsd 

IBM Speech Viewer 

Alaw 

alaw 

Aaw ADPCM 

MUlaw 

mulaw 

MULaw ADPCM 

IBM Alaw 

ibm alaw 

IBM Aaw ADPCM 

IBM MUlaw 

ibm mulaw 

IBM Mulaw ADPCM 

OKI_ADPCM 

oki adpcm 

OKI ADPCM 

DVI.ADPCM 

dvi adpcm 

DVI ADPCM 

IBM ADPCM 

ibm adpcm 

IBM ADPCM 

MS ADPCM 

microsoft adpcm 

Microsoft ADPCM 

DIGISPEECH 

digistdl 

BM DIGISPEECH (standard) 

DIGISPEECH 

digifix 

IBM DIGISPEECH (fixed format) 

AVC ADPCM 

avc adpcm 

IBM AVC ADPCM 
(audio-visual connection adpcm) 

CT ADPCM 

ct adpcm 

Creative Labs ADPCM 


Table 5-6. Format tags 


This list presents the most common and some product-specific proprietary 
recording formats (as in the case of SpeechViewer, and AVC, or Audio/Visual 
Connection formats). As mentioned earlier in the chapter, the ADPCM formats 
represent a method for storing and or compressing the data samples to occupy 
less space. The techniques to accomplish this vary from implementer to imple- 
menter, and care should be taken to consider that if you wish to utilize 
ADPCM storage mechanisms, to take into account what hardware will be 
needed by your or your customers systems to both record and playback the 
waveaudio. Before you ever change the format tag, or any other device mode 
dependent setting from the default (normally PCM), you should query the 
device to see if it supports the mode you wish to use. This can be accomplished 
by: 
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“capability wavel extended format tag pcm 
bitspersample 16 samplespersec 44100 channels 1 
mode pi ay wait” 


If the format, with the set of mode parameters specified, (bits per sample, 
etc.) queried is supported, by the device, the MCI will return “true.” If the for¬ 
mat you wish to use is supported, then to set the format tag to be used, do the 
following: 


“set wavel format tag ms adpmc wait” 


This will set the format tag to the audio compression format you selected. 
In this case it will be Microsoft ADPCM. The set command can be used to set 
all, or some, of the audio format parameters. 

When you know all the format parameters you want to use then do one set 
command for all of these parameters. This will improve the performance of the 
device by allowing it to load any DSP modules or perform setup based on the 
final audio format setup. 


“set wavel format tag pcm samplespersec 22050 

bitspersample 16 channels 2 wait. 


This sample sets the device to PCM 22 Khz 16-bit stereo audio. 


Gain 


In the playback section, before playing back an audio file the application 
should query and set the volume on the device as necessary. It is equally 
important, if not more so, that for recording, the gain on the microphone be set 
to a useful level to get good results. To set the gain we must gain access to the 
ampmix device connected to the waveaudio device instance. (Note an amp- 
mix device instance is opened and connected to the waveaudio device instance 
by the waveaudio device.) To gain access to the ampmix, use the connec¬ 
tion message. Here is a simple example of how to query and set the gain level: 
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ulRC = mciSendString(“open waveaudio alias wavel shareable wait”, 

pszReturn,strlen(pszReturn) ,NULL, 0 ); 

ulRC = mciSendString(“connection wavel query type wave stream 

alias ampl wait”, pszReturn, 
strlen(pszReturn) .NULL, 0 ); 

/* Query current GAIN setting */ 

ulRC = mciSendString(“status ampl gain wait”,pszReturn, 

strlen(pszReturn) .NULL, 0 ); 

/* Set GAIN on the microphone */ 

ulRC = mciSendString(“set ampl gain 90 wait”,pszReturn, 

strlen(pszReturn) .NULL, 0 ); 


In this sample we opened the waveaudio device and queried the device 
instance connected to its wave stream connector. The alias ampl is associat¬ 
ed with that ampmix device instance. This alias can now be used to send 
string commands to the ampmix device instance. We then query what the cur¬ 
rent gain level was set to, and then set the level to what we want it to be. Be 
aware that the gain keyword for the set and status commands, refers to a 
percentage setting between 0 and 100 on the microphone. 

Recording 

Once the sampling rate, BPS, number of channels, format, and if necessary, 
audio compression type, have been set, you are prepared to record. The 
mciRecordAudioFile provided its own interface, and if you are supporting 
recording waveaudio within your application, you will have to decide how you 
want to present a recording interface to the user. The mechanism for recording 
is not very different from the one for playing a waveaudio file: 


record wavel from 0 to 10000 wait” 


The example demonstrates how to perform a simple recording. It specifies 
beginning and ending positions of where to perform the recording operation. 
This is very important; if for some reason, you have already made a recording 
and wish to go back in the audio data, and re-record over some of it by chang¬ 
ing only the from keyword, the record will be done from that position. 
However, to do this, you must add one more keyword to the command, over¬ 
write. Therefore, “record wavel from 2000 to 5000 overwrite wait” will 
re-record for 3 seconds, over whatever was there before. 
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Saving the Recording 


You can reset and re-record the data from and to, whatever starting and end¬ 
ing points you would like and as much as you like. Then, once you have stored 
the recording as you want it, you can then save away the data by performing 
the following command: 


save wavel myfile.wav wait” 


Once this is done, the audio data will be saved away to whatever “filename” 
was specified. If you wanted to package several files within a bundle file, it is 
also acceptable to specify the compound file name and the element name in 
place of “filename.” For example, if you specified, “Archive.bnd+StonesLve,” the 
compound file “Archive.bnd” would be opened (or created, if it was not found), 
and the element “StonesLve” would be added into it. 

User-driven Recording 

If you want to allow the user to control the size of the audio data, or if you 
want the user to correct themselves by re-recording over the audio data, then 
do not specify either the from or the to keywords to the record command, and 
use the notify keyword instead of the wait keyword. Then query the length of 
the recorded audio via the status command when the recording is done. 


ulRC = mciSendString( “status wavel length wait” 

(PSZ)pszReturn, strlen(pszReturn) ,NULL, 0 ); 

ulLen = _atol( pszReturn ); 


This command returns the length of the audio data in the time format that 
the device is presently set to. If you control the record process visually via 
either a button click or menu selection, remember to inhibit, or serialize access 
to your record function(s). When the user selects the menu item to stop or, for 
instance, presses the record button again, you will receive notification of these 
events by PM. At this point you can issue a command to halt the recording 
process. To do this, issue the stop command: 


strcpy( szCommand, “stop wavel wait” ); 

ulRC = mciSendString( (PSZ) szCommand, (PSZ)pszReturn, 

strlen(pszReturn) .NULL, 0 ); 
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It is very important to keep in mind that it is possible for you to run out of 
working space during the recording process. You may receive a return code of 
MCIERR_TARGET_DEVICE_FULL. This indicates that the drive where 
MMPM/2 was storing its recording buffers has run out of space to store any 
more data. It is possible for you to get around this by querying, then changing 
the default workpath for MMPM/2. This would be done as follows: 


char szWorkPath[CCHMAXPATH]; 

char szNewPath[CCHMAXPATH]= “E:\\TEMP”; /* a 10GB RAID Array ! */ 

/* Save current work path so you can reset it after you’re */ 

/* done recording. */ 

mciQuerySysValue( MSV_W0RKPATH , szWorkPath ); 

/* Use DosxxxO api’s to determine where sufficient space is available */ 

/* Set New MMPM/2 WorkPath */ 

mciSetSysValue( MSV_W0RKPATH, szNewPath ); */ 

/* Perform your recording */ 


/* RESET the WORKPATH to the original */ 
mciSetSysValue( MSV_W0RKPATH, szWorkPath ); 


This example allows the application to accommodate the requests of the user 
(of course, sufficient disk space on some drive will be necessary to satisfy the 
requirement). 

The last keyword of the record command allows for insertion of new data to 
a previously loaded, or created data element. The format for this is as follows: 


record wavel insert notify 


This causes new data be recorded into the wavel in the data format the 
device is currently set to. Now that you have the audio recorded, you can save 
it by using the save command as in the previous section. Obviously, once you 
are done with the waveaudio device, do not forget to close it: 


“close wavel wait 
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EDITING 


The editing process is probably considered the most dreaded part of authoring 
multimedia content. Getting the recordings just right will require as much 
time as necessary to get the final output just the way you, or the user wants it. 
In the MCI there are a few basic editing functions: cut, copy, paste, delete, 
undo, and redo. 

Cut; Copy; and Paste 

Editing does not apply solely to the recording process, so we now discuss the 
cut, copy, and paste commands with respect to both record, and playback. 
You can mix data between two (or more) audio data file (or even just buffers), 
or copy a piece of one audio file and create a whole new one, as long as you are 
aware of some of the limitations of MMPM/2, in the area of data editing: 

1. The string interface utilizes ONLY the Clipboard. To use a buffer in mem¬ 
ory, you will need to use the procedural interface ( mciSendCommand ). 

2. When you wish to convert the data from one format to another insure that 
the device supports the target format to which you wish to convert. 

3. MMPM/2 only supports data conversion in the following ways: 


From 

To 

Mono 

Stereo 

Stereo 

Mono 

11 Khz 

22.05 Khz or 44.1 Khz 

22.05 Khz 

11 Khz or 44.1 Khz 

44.1 Khz 

11 Khz or 22.05 Khz 

8-bit 

16-bit 

16-bit 

8-bit 


Table 5-7. Editing audio data conversions 


4. No data smoothing (or data correction) is performed by MMPM/2 on the 
paste operation. 
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If you keep these limitations in mind, any editing you perform should be 
quite simple. The editing commands can utilize either the clipboard, or via the 
procedural interface, memory buffers. For most purposes the clipboard can do 
everything we need. 

The cut, copy, and paste functions are almost identical, and accept almost 
the same keywords: 


/* Assume time format of Milliseconds */ 

“Cut wavel from 1000 to 2500 wait” 

“Paste wave2 from 1000 wait” 
or 

“Copy wave2 from 5000 wait” 

“set wavel SamplesPerSec 44100 wait” 

“Paste wavel from 1000 to 4000 wait” 


The paste command also accepts the convert keyword which instructs the 
MCI to convert the data in the clipboard to the format of the target device (for 
limitations, see the previous figure). When you perform any one of these opera¬ 
tions, you should make certain the both the source and target device are oper¬ 
ating under the same time format, so that when you specify either begin and 
end point (or both) that the operation is performed correctly. The cut/paste 
example cuts 1500 units of measure out of the audio buffer of device “wavel,” 
and then pastes it to device “wave2.” Notice also that this operation made the 
assumption that BOTH source and target devices not only were operating 
under the same time format, but same content format (i.e., BPS, 
SamplesPerSec, etc.). 

In the copy/paste example, however, we see that the Samples Per Second of 
the target device were modified, and that the paste operation was then per¬ 
formed. For that command to be valid, it must be assumed that the data for 
device “wave2” was recorded at 44.1Khz. However, if the data was not stored 
at that data rate, then for the paste operation to succeed, the convert key¬ 
word must be used: 


“Paste wavel from 1000 to 4000 convert wait 


Notice also, that this command only pasted 3000 milliseconds (or 3 seconds) 
worth of data from the clipboard, regardless of how much recorded data was 
present in the clipboard. Make certain that when you paste, either sufficient 
data is in the clipboard to support the command you want, or that you modify 
the from or to accommodate the amount of data you have. You could simply 
re-copy/cut the amount of data you want into the clipboard, and then perform 
the paste. 
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Undo/Redo 


We briefly mention the undo and redo commands, at the beginning of the sec¬ 
tion, and while we do not go into detail on their use, they are important. These 
two commands are very useful because they provide the freedom to modify 
your data, and if you change your mind, undo it, or, if you did not want to 
undo something you had done and want it back the way you had it before, to 
redo it! 

The undo and redo commands are totally opposite commands, each backs 
away from what the other just did. Here are some examples: 


“Cut wavel from 1 to 5000 wait” 

“Paste wave2 from 1000 to 4000 wait” 
“Play wave2 wait” 

/* Didn’t like the way it sounded */ 
“Undo wavel wait” 


Now, the data that was pasted into the “wave2” device has been undone, or 
removed, from the devices buffers. Note one important thing: once an undo 
has been performed (the same applies to redo) at whatever the last position in 
the data you were has been lost, and the media position resets to zero. If you 
change your mind again, and want the data back as you had it after the paste, 
substitute redo in place of the undo in the last string, and the data will be 
back to the way you had it. 

Also, a command we did not mention before that is important is the delete 
command. Not grouping it with the other editing commands was intentional on 
our part. As the word itself implies, delete, is a rather permanent operation, 
and its use requires that developers be prepared to handle certain things them¬ 
selves. The delete command will eliminate from the device, audio data buffers, 
within the time range you specify. For instance, specifying: 


“delete wavel from 1 to 1000 wait” 


will cause the first second (again, let us assume millisecond format) of audio 
data from device “wavel” to be discarded. This command is very different from 
cut, since NOTHING is saved of the data that was just removed. The stream¬ 
ing buffers will be rearranged internally, even possibly new sets of buffers allo¬ 
cated to store the data. For this reason, we recommend that the application 
perhaps keep a copy of the data for the selected buffer area itself, in case the 
user wishes to undo the delete, given that MMPM/2 will no longer have that 
data available. Also, the specific position of where the data began and its 
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length should also be stored away by the application for the same reasons. 
These two pieces of information are what we refer to when stating that the 
developer needs to be prepared to handle a delete operation in a unique way 
in comparison to other editing commands. 


MIDI—ELECTRONIC MUSIC 


MIDI, short for Musical Instrument Digital Interface, was developed in the 
late 70s and early 80s. The first standard, or MIDI 1.0, released in 1982, pro¬ 
vided a somewhat standard way for the emerging portion of the music industry 
which made of use of electronic keyboards and synthesizers, to have some con¬ 
trol of any number of like and dislike instruments via one mechanism. This 
mechanism was based on a serial connection between all devices, operating at 
31250 baud. The reason for this speed was that given current hardware of the 
time, to make this option technically feasible and cost effective to manufacture 
for all of the hardware vendors, compromises had to be made. 

Before going any further, we should make note that, as we have mentioned 
before, MMTIME is the standard unit of time measurement in MMPM/2. 
MMTIME equates to 1/3000 second. A keen observer would note that the data 
rate of 31250 baud equates to 3000 bytes/sec, and might deduce that 
MMTIME would be based on that measurement. That observer would be quite 
correct. It so happens that MMTIME is convertible to almost any time format 
utilized in multimedia, and thus it is a prime candidate to use for keeping not 
only timing, but system-wide synchronization based on that timing. 

Now, the hardware portion of the MIDI specification calls for all devices to 
be connected in a chained fashion, with the hardware on any given device, not 
only allowing for reception of information (MIDI-IN), but for the pass-through 
(MIDI-OUT/Through) of that very same information. This is because the usage 
of MIDI is based on the principle of Master/Slave (not unlike the concept of 
Master/Slave Streams), whereby one synthesizer or computer, can control the 
function of the rest of devices on the chain. In normal MIDI operations, this 
master is referred to as the controller, or master controller. Normally, musi¬ 
cians make arrangements of music where the instruments are “blended” in, in 
a layered fashion, and usually musical transitions on one instrument signal 
changes in the composition for the other instruments as well. That is how 
MIDI is designed to work, where the information on the musical score for one 
instrument can or does control the flow of the others. Interestingly enough, the 
control can pass from one master instrument, to another having only ONE 
master is not necessary. 

To implement this concept of flow of control, and obviously, packaging all 
the data relating to the musical piece itself (the notes, tempo, etc.), be a consis- 
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tent, robust, yet extensible data transport system was needed. The designers of 
MIDI chose to design the software portion, to perform not unlike a data trans¬ 
fer protocol works in a terminal/communications package. The MIDI protocol 
was designed around a set of standard messages, which included not only key, 
and note information, but timing and instrument selection messages. The 
number and variety of messages have grown and evolved as the standard has 
matured. What that essentially means is that, as more and more features were 
added to synthesizers—drum machines, and the like—the more function has 
crept its way into the standard. 

For this reason, a proposal is currently awaiting approval among all the 
hardware vendors: MIDI v2.0. This new standard equates to a “re-leveling” of 
the playing field, because the non-destructive way to “extend” the MIDI proto¬ 
col was via a feature called the “System Exclusive,” whereby one device could 
not only take control of other devices complete setup, but the device could 
essentially, re-invent itself, without other devices getting involved in the 
process. This means more features for musicians to play with, but more havoc 
for software designers and developers wishing to create software for composi¬ 
tion and editing musical sequences. Which, incidentally, is where the MMPM/2 
logical MIDI device gets its name, sequencer. Sequencing, is the industry 
phrase used to describe the composition of music in an electronic or digital 
form. That is because all the musical information in a score, down to the Nth 
timing change, or key transposition, is sequenced, or, placed in order with all 
other events in that score. That sequence information is then placed in a file 
which is made up of what equate to packets of information for the devices to 
receive and decipher at their discretion. MIDI sequences provide for up to 16 
channels of information per sequence, although certain manufacturers have 
developed ways around that by utilizing various forms of the System Exclusive 
(or SysEx) message. The first ten channels, or tracks of music are reserved pri¬ 
marily for what are called Extended Synthesizer, more on that a little later. 
The remaining 6 channels are for usage by Base-level synthesizers (tracks 
13-16) and unused channels (tracks 11 and 12). 

Synthesizers provide a basic number or selectable instruments (currently 
128), based on the MIDI standard, which can be mapped in to the synthesizers 
hardware by sending a message to select an instrument. Most sound cards pro¬ 
vide at least the basic set, while others provide several selectable sets of 
instruments from which to choose. The default configuration of the Sequencer 
device in MMPM/2 is set up around a configuration referred to as general- 
MIDI. This is because this configuration covers the vast majority of the capa¬ 
bilities of both sound cards, and MIDI synthesizers available today. When 
MMPM/2 is installed, and a device that supports MIDI is selected, this configu¬ 
ration will already be set up for you. 

Extended MIDI provides basically one major improvement over basic MIDI, 
and that is the ability to support up to 16 voice polyphony. What difference 
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does that really make? Depending upon your hardware setup, the same differ¬ 
ence a trio of singers has to a choir. Actually, to be more precise, it could be dif¬ 
ference between a small band and an orchestra, because depending on how the 
instrument mappings are made, the effect of a full orchestra could be 
recreated. 

MIDI has some advantages over waveaudio. The first and most notable, con¬ 
tent file size. A MIDI score one minute in length will be magnitudes in size 
smaller than any waveaudio recording. Also, MIDI does have the flexibility of 
easier modification of the content via a sequencing program. Up until recently, 
however, the general quality of MIDI music on a PC was not exactly what you 
would call exciting. This is because of affordability; hardware vendors like 
Creative Labs® used what were called FM (or frequency modulation) synthesiz¬ 
ers, which can only render an approximation of the sound of an instrument. 
Fortunately, in the past year or two, more and more vendors have introduced 
sound cards based on an a very old scheme used in programming, table look 
up. These synthesizers are called Wavetable synthesizers, because they store 
the actual digital recording of an instrument (usually in some sort of ROM), 
which is then used to recreate the music, by blending the digital data into one 
output stream. This way, the sound output sounds more like real instruments, 
and the user maintains the flexibility of having a wide variety of instruments 
from which to choose for composing his or her music. 

The one drawback of MIDI is timing. Because of the way MIDI was original¬ 
ly designed, there was not a lot of function for maintaining timing outside of 
what the synthesizers provided for their own internal use and whatever the 
master controller supported. Since for the most part, most professionals use a 
PC for their master controller, its the system’s responsibility to maintain the 
timing of messages. This is where MIDI has its impact on system resource. 
Just as waveaudio consumes disk space, and CPU in most cases, MIDI makes 
use of less disk space, but can in some instances require more CPU resource 
just to maintain the timing of a score. 

Playing MIDI 

Unfortunately, MMPM/2 only currently supports the process of MIDI playback, 
so that will only be the extent of what we cover here. Recall, the name of the 
MIDI device under MMPM/2 is called the sequencer. Thus, to gain access to 
MIDI you can open the device this way: 
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char szCommandString[128]; 

USHORT usMidiDevicelD; 

char pszReturn[MCI_RETURN_STRING_LEN]; /* Define as you wish */ 
ULONG ulRC; 

strcpy( szCommand, “open bach.mid alias Midi wait” ); 
ulRC = mciSendString(szCommand, pszReturn, 

MCI_RETURN_STRING_LEN, 0, 0 ); 

/* Assuming success */ 

usMidiDevicelD = (USH0RT)_atoi( pszReturn ); 

/* And to play the device */ 

strcpy( szCommand,”play Midi” ); 

ulRC = mciSendString( szCommand, NULL ,0, 0, 0 ); 


The example opens the default sequencer device, and then proceeds to play 
back the musical score. As in the waveaudio playback example, we perform an 
implicit form of loading the file where the system determines the device type 
for us by using the standard file associations installed in the system. In some 
instances, this method may be simpler to use. 


AUDIO CONNECTIONS 


If you have a home entertainment system, VCR, or any other audio equipment, 
you have had to deal with one of most frustrating and down-right infuriating 
inventions ever devised—Cables. Cables connect the CD player, tape deck, and 
record players (yes, some of us still listen to “those old vinyl things”), to the 
stereo system/audio-amplifier. Then, more cables connect the stereo/amplifier 
(amp) to the speakers. The more equipment, the more cables to deal with, and 
the more complicated the setup. 

Connectors, and the MMPM/2 ampmix device are really quite a pair. When 
you open any audio device under MMPM/2, you implicitly get an instance of 
the ampmix with default connections between data source and target already 
established. For instance, the default connection when you open the waveau¬ 
dio device, you can determine the default connection by: 


ulRC = mciSendString(“defaultconnection type wave stream wait”, 

pszConnection, strlen(pszConnection), 0, 0 ); 


This call returns name of the default connection of the waveaudio device. 
Interestingly enough, this default connection is to the ampmix device. 
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Beginning to see where the analogy of cabling comes in? In just the same man¬ 
ner that we connect the devices in our entertainment systems, changes in the 
connections between logical devices can be made. For instance, if you want to 
connect your CD-ROM directly to your waveaudio device, you could do it. Of 
course, this would mean that your sound card and its device driver would have 
to support data streaming at 44.1Khz, 16-bit, stereo. If this is the case, here is 
how the connection would be made: 


/* Assuming the both the waveaudio and cdaudio device */ 
/* have been opened previously */ 

char szConnection[128]; 

char pszReturn[MCI_RETURN_STRING_LEN]; 

ULONG ulRC; 


strcpy ( szConnection, “connector cdaudio enable type CD stream wait”); 
ulRC = mciSendString( szConnection, pszReturn, 

MCI_RETURN_STRING_LEN, 0, 0 ); 
ulRC = mciSendString( “play cdaudio”, NULL, 0, 0, 0 ); 


In this example, a connection between the CD audio device and the ampmix 
device was made and, since the default “audio out” connection is the default 
waveaudio device, a stream was implicitly created to stream the data from 
the CD-ROM out to the sound card. The connection that was created was rout¬ 
ed via the ampmix device. This is because even with the most complicated of 
wiring setups there still has to be one focal point where all data must be chan¬ 
neled through. That is not to say that the Amp/Mixer device itself was too ter¬ 
ribly involved in the whole process of the stream, quite to the contrary. Its sole 
purpose, in this instance, is to establish the connection between the two other 
devices. While the ampmix can do these services and more, the involvement is 
usually one of what could be equated to a diplomat, trying to maintain some 
semblance of order to it all. 

Here is a list of some of the connectors supported by MMPM/2: 


Device Type 

Connectors 

waveaudio 

wave stream, headphones, speakers, microphone, line-in, line-out 

sequencer 

MIDI stream, headphones, speakers, line-out 

ampmix 

amp stream, headphones, speakers, microphone, line-in, line-out 


Table 5-8. Audio connector types 
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Table 5-8 is only a subset of the entire connector list, and it refers only to 
waveaudio, and its related devices. It is important to note that the number 
and types of connectors can vary on each device, and also from implementation 
of one device type to another. 

Also, although devices have their own set of supported connectors, connec¬ 
tions between different connectors themselves are available. For instance, it’s 
possible to connect the line in to the audio out. This is analogous to plugging in 
a musical instrument directly into audio amplifier. Audio is sent directly out 
the speakers from the instrument. 

Each device has its own set of supplied connectors, and connections between 
different connectors themselves can be made. It should be noted that connect¬ 
ing the line in of one device to the line out of another device may not necessari¬ 
ly be allowed. Because, unless the data types are compatible there is no way 
for one device to interpret the data it is receiving from the other device. Such 
connections are completely disallowed and will be rejected by the MCI. For 
example, it is not possible to connect the line out of the waveaudio device to 
the video in of the digital video device. Here is a short list of some of the 
audio-related connections (by connector type) which are allowed: 


Connector type 

Connections 

audio-in 

headphones 


speakers 


line out 

line in 

line out 


audio out 

amp stream 

wave stream 


midi stream 


Table 5-9. Connector types and their supported connections 


We have mentioned previously that certain device types which are related to 
audio playback and recording, but are not at present, really “devices” per se. 
These are: headphones, microphone, and speakers. It was considered that 
eventually there would be a need for these devices, because consider an intelli¬ 
gent microphone with an adjustable gain level built in. Such a device would 
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have controllable attributes which MMPM/2 could encompass. So far, some of 
this technology does not exist (at least not as commercially available products). 
Therefore, these devices exist as chiefly attributes within the ampmix device 
itself, and are manipulated by the ampmix device. If you were to open one of 
these devices, there would be an implicit instance of the ampmix created to 
handle all the operations performed on any of these devices. Our point of view 
is that if you ever have to manipulate attributes which may be associated with 
any of these devices, access the ampmix device directly. 


PLAYLISTS 

Buffer Playback and Recording of Audio Data 

Perhaps where MMPM/2 has the most power and flexibility for the program¬ 
mer is in the area of playlists. Playlists can be considered just like macros or 
functions in programming. There are a certain set of instructions, or com¬ 
mands that playlists can have in them. There are parameters for the data, the 
size of the data, and information about what to do once this command has been 
performed. 

The commands which are supported by the playlist functionality in 
MMPM/2 are as follows: 


Command 

What it does 

NOP.OPERATION 

Dummy place holder 

BRANCH_OPERATION 

Goes to another instruction 

CALL.OPERATION 

Calls to a subroutine 

RETURN.OPERATION 

Returns from a CALL operation 

DATA_OPERATION 

Specifies a buffer 

LOOP_OPERATION 

Specifies iterations for given command 

MESSAGE_OPERATION 

Send back MMJVTCIPLAYLIST message 

CUEPOINT.OPERATION 

Send back MM_MCICUEPOINT message 

EXIT.OPERATION 

Specifies the end of the playlist 


Table 5-10. MMPM/2 Playlist command table 
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Looking at the table, you can see why we chose the analogy of programming 
commands to describe playlists. You can now think of a playlist like a script 
that can be executed. 

Before we can use playlists, it is important to consider that playlists operate 
solely from memory. Whatever data is going to be employed must have space 
allocated for it. If you are going to play a file, you have to read it into memory. 
If you intend to record into a playlist, then you will have to allocate sufficient 
memory to store some amount of the audio data that will be recorded and kept 
in memory. Your application should write out fill memory buffers to files as 
soon after they are filled. You can refer to the equation for calculating the 
number of bytes per second of audio, to help you determine how much memory 
you must allocate. Assuming we’re going to play from a playlist, here is a brief 
example of how to set up and play a waveaudio file: 

typedef struct PlayList { 

ULONG ulCommand; 

ULONG ulOperandl; 

ULONG ulOperand2; 

ULONG u!0perand3 
} P LAY_LI ST, *PPLAYLIST; 


#define MM_ITSDONE 111 

P LAY_L I ST mmPlayList [ 1 ][ 3 ] = 

{ 

DATA_OPERATION, 0, 0, 0, 

MESSAGE_0PERATI0N, 0,MM_ITSDONE,0, 
EX IT_0PERAT I ON, 0, 0, 0 


/* MAIN program */ 

MMAUDIOHEADER mmAudioHead; /* defined in MMI00S2.H */ 

MCI_SET_WAVE_PARMS mmSetWaveParm; 

MCI_0 P E N_PA RMS mmOpenP; 

PLAYLIST_STRUCTURE_T mmPlay List[1][2]; /* Define 1 playlist */ 

/* with 2 commands */ 

PV0ID pAudioData; 

MCI_PLAY_PARMS mmPlayP; 

USH0RT usDevicelD; 

HEV hSem; 

/* Create a semaphore to serialize us.*/ 


Figure 5-4 . Audio Playlist Sample 
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DosCreateEventSem( NULL, &hSem, DC_SEM_SHARED, FALSE); 
h F i 1 e = mmi oOpen( “c: Wmmos2\sounds\\cuckoo. wav” ); 

mmioGetHeader( hFile, &mmAudioHead.); 

/* Determine the size of the audio data itself.*/ 

ulData Size = mmAudioHead.mmXWAVHeader.XWAVHeaderInfo.ulAudioLengthBytes; 

usBPS = mmAudioHead.mmXWAVHeader.XWAVHeader.usBitsPerSample; 

/* Same operation applies for SamplesPerSec, and Channels*/ 

pAudioData = (PV0ID)mal1oc( ulDataSize ); 
mmioRead( hFile, pAudioData, ulDataSize ); 
mmioClose( hFile ); 


/* Set the Data in the play list */ 

mmPlay List[0][0].ulOperandl = (U LONG)pAudioData; 

mmPlay Lis t[0][0].ul0perand2 = ulDataSize; 

mmOpenP.pszDeviceType = “waveaudio”; 
mmOpenP.pszAlias = “wavel”; 
mmOpenP.pszElementName = mmPlayList; 

mciSendCommand( 0, 

MCI_0 PEN, 

MCI_WAIT | MCI_0 P EN_P LAY LIST | MCI_0PEN_TYPE_ID | 

MCI_OPEN_SHAREABLE, 

(PV0ID)&mm0penP, 

0 ); 

usDevicelD = mmOpenP.usDevicelD; 


/* set the BPS, ( and SamplesPerSec, and Channels, etc. )*/ 

/* since we created an alias...we can use it here*/ 

sprintf( szCommand, “set wavel %s %1 wait”, “bitspersample”, usBPS ); 

mciSendString( szCommand, NULL, 0, 0, 0 ); 

/*Repeat the previous two steps for each individual setting *// 


/*SamplesPerSec, Channels, format tag, etc. or.*/ 

/* 

/* Now that the device is set up the way we want it*/ 

/* we can just do a very simple play... */ 


Figure 5-4. Audio Playlist Sample (Continued) 






220 Developing Multimedia Applications Under OS/2 


mciSendString( “play wavel notify”.hWnd.); 

/* Do whatever we need to.wait for notification */ 

DosWaitEventSem( hSem, SEM_INDEFINITE_WAIT ); 

mciSendString( “close wavel wait” ); 

DosCloseEventSem( hSem ); 

/* Free the memory*/ 
free( pAudioData ); 


/* EXTREMELY SIMPLE Notification Handler */ 

MRESULT EXPENTRY mmWindow! hWnd, Message, mpl, mp2 ) 
{ 


switch! message ) 

{ 

case MM_MCIPLAYLISTMESSAGE: 
ulCuePointID = mp2; 

/* Do whatever we need to..*/ 
DosPostEventSem! hSem ); 

break; 


return! WinDefWindowProc! hWnd, Message, mpl, mp2 ) ); 


Figure 5-4. Audio Playlist Sample (Continued) 

This example may seem involved, but it is possibly the simplest one we 
could give. The true possibilities of what can be done with playlists are what is 
possible utilizing the “subroutine” and “looping” function of playlists. A broader 
explained table for the playlist commands was defined the chapter on the MCI, 
and we refer to it whenever we discuss a particular command. For each exam¬ 
ple, we will provide, place the playlist in the example with the code presented 
at the beginning of the section to get the right perspective of what’s being done. 

Data Command 

The DATA_OPERATION command specifies the buffer to be used to perform 
a play or record operation. Perhaps the most important part of this command is 
the fact itself that the third operand is updated with the amount of data that 
has actually been consumed (playback) or produced (record) by the device. It is 
updated during its operation, and it is possible to query the data in this field, 
as long as you keep in mind that it could possibly change, even as you read it! 
Our Advice, is that unless you are processing a message or cuepoint command, 
do not even query it. 
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Message Command 

The MESSAGE_OPERATION command could be considered to be akin to an 
event notification, because a message will be sent to you when this command is 
reached in the playlist. The same concept that applied to the example we pre¬ 
sented, passing an ID as the returned user parameter, can prove very useful. If 
you create memory buffers for data yourself, and are controlling the device at a 
very granular level, you can choose your applications course of action at this 
point, possibly even stopping device, and exchanging which playlist the device 
should use! However, it should be noted that this command is not intended to 
be used for tracking data consumption by the system, but mainly as a land¬ 
mark for where the playlist processor is in your script. 

Cue Points 

The CUEPOINT_OPERATION command is identical the setcuepoint string 
command. What we didn’t discuss before was a real “in-practice” use for this 
command. Whether you use playlists, or the string interface to set cuepoints is 
a matter of choice. Cues are the basis for tracking events. Being able to track 
events places you in control of the flow of data. 

Consider one possible scenario. In a game, the user sees an animated figure 
walking, the figure falls into a manhole. From your application, you start to 
play a waveaudio file that is the sound effect for someone falling into a hole. 
After a period of time, the person hits the bottom of the hole. Then you play a 
different sound to represent the sound of the person hitting the ground. But 
there is a question to all this. How did you know when the person hit ground? 
Either you could control this via a timer yourself, and control the period for 
which the sounds plays, or you can use a cuepoint to tell you when a specific 
point has been reached. At that point, you could determine the players’ fate, 
and either allow them to continue falling or put them out of their misery. Here 
is what an example of this might look like in a playlist list. 


#define FALLING_DONE 1000 


PLAYLIST mmFallList [1][4] 


CUEP0INUMERATION, FALLING_DONE, 
MSECT0MM(5000), 0, 
L00P_0PERATI0N, 5, 4, 0 
DATA_0PERATI0N, 0, 0, 0, 
BRANCH_0PERATI0N, 0, 1, 0 
EXIT_0PERATION , 0, 0, 0 
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In this example, we set a cuepoint to “fire” 5 seconds into the playback. The 
playlist will continue looping the audio data for 5 iterations and then exit the 
play list. Let us assume that the waveaudio lasts for a couple of seconds, that 
means that the loop can take up to 10 seconds. Halfway into the loop, the 
MM_MCICUEPOINT message will be issued, at which time, we can do what¬ 
ever we choose to do. We leave the decision to the readers imagination. 


Looping 


As we presented in the previous example, the LOOP_OPERATION command 
can be useful to continue performing repetitious tasks without direct interven¬ 
tion for the duration of the loop. In the last example, however, we merely 
assume that the audio data lasted for a couple of seconds. In real practice it is 
very important that you know the amount of time that the audio lasts. To 
determine the number of seconds a piece of audio data last for, take the same 
equation used to described the number of bytes required to store N number of 
seconds of audio, and do as follows: 

NumSeconds = NumBytes / ( (BPS/8)* SamplesPerSec * Channels ); 

This tells you how long the audio will last. You can then begin to determine 
how many loops, if any, you wish to repeat the sound. The loop command 
requires that you specify exactly to which command, by offset to relinquish 
control to. Also, if you happen to be processing either a cuepoint or a message 
from a MESSAGE_OPERATION, (assuming that you have serialized access 
to the playlist) you can determine “where you are”, and decide how to proceed. 

Branching 

In the previous example, we use the BRANCH_OPERATION command. This 
command is exactly like performing a GOTO in a program. While GOTOs are 
normally frowned upon in general programming, anyone doing low-level devel¬ 
opment (such as device drivers, and such) will tell you they are absolutely nec¬ 
essary. The branching command can be used to redirect and the execution of 
the playlist. For instance, after a certain amount of loops, it is possible to set a 
branch instruction to go and play a different sound, and then return. 
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PLAYLIST mmFal1ThudList [1][4] 

{ 

LOOP_OPERATION, 3, 3, 0, 

DATA_0PERATI0N, X, Xx, 0, /* Falling sound */ 

BRANCH_0PERATI0N, 0,0,0, 

DATA_0PERATI0N, Y, Yy, 0, /* Thud sound */ 

EXIT_0PERATION, 0, 0, 0 

}; 


This play list uses two sounds (X and Y), and once the sound for falling (X) 
has looped three times, sound of the person hitting the ground (Y) would be 
played. 

Subroutines 

As mentioned previously, playlists also have the capability for supporting sub¬ 
routines. The commands for doing this are: CALL_OPERATION (like 
GOSUB in BASIC) and RETURN.OPERATION. The call command does just 
as it says, it makes a “function call,” because the position of the instruction 
immediately following the call command is saved, and is where execution 
resumes when the RETURN_OPERATION command is reached in the sub¬ 
routine. These two are probably the most useful functions of playlists, yet they 
are not described very clearly in the references. 


PLAYLIST mmFal1BoinkThudList El][4] 


L00P_0PERATI0N, 3, 3, 0, 
DATA_0PERATI0N, X, Xx, 0, 
BRANCH_0PERATI0N, 0,0,0, 
CALL_0PERATI0N, 0, 6, 0 
DATA_0PERATI0N, Y, Yy, 0, 
EX IT_0PERATI ON, 0, 0, 0 
DATA_0PERATI0N, Z, Zz, 0 
RETURN_0PERATI0N, 0, 0, 0 
}; 


/* Falling sound */ 

/* Call subroutine */ 
/* Thud sound */ 

/* Boink sound */ 


With only a slight modification, we are able to create a totally different 
sequence of events. By substituting different sounds in place of the data com¬ 
mand in the subroutine (playing buffer Z) the playlist can be reused to create 
just about any effect you may want. 
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What is digital video? First of all, video can be the visual presentation of an 
image that changes over time. The classic examples of this are TV or motion 
pictures playing at your local theater. A video can consist of a series of images 
displayed one after the other over a period of time to give the effect of motion, 
hence the term motion video or motion picture. Typically, it is necessary to pre¬ 
sent at least 15 images a second to achieve this effect of motion without the 
perception of individual frames or “jerky-ness.” Motion pictures in the United 
States display 30 images, or frames, a second to give a real motion effect. 

Digital video is a form of video that has been capture through a hardware 
device and converted to Os and Is. Computers are great at dealing with num¬ 
bers, so for a computer to be able to manipulate a video, it is typically digitized, 
or converted to a form the computer can deal with. Once in this digital form, 
the bits and bytes of data can be altered, enhanced, or compressed. As video 
data is digitized, the information within each image of a video, like color, is 
captured. Video is digitized by taking a series of snap-shots over time of the 
video source. Put the images together, and display them one at a time over the 
same time period and you get a digital representation of the video. 

The quality of this video, or how closely it reproduces the original, is affected 
by many things. The amount of color information and the number of frames 
per second that are displayed are key to this quality. The number of frame per 
second is called the frame rate. Color information can be stored in various 
ways. One way is to store the color data in terms of the three primary colors: 
red, green, and blue. RGB is an acronym used to describe colors stored in this 
manner. An image itself is made up of pixels, or individual points. Each of 
these points can be represented by an RGB value. The number of bits for each 
pixel used to store the color information is called color depth. 
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Displays used on computers today can display images and graphics in a 
range of color depths, for example, 4-bit, 8-bit, 16-bit, and 24-bit are common. 
In standard VGA mode, 4-bit color is supported at 640x480 resolution, which 
means that each pixel can be one of 16 colors. In super VGA modes and other 
video display modes, 8-bit, or 256 colors and 16-bit, or 65536 colors can be used 
for each pixel at 640x480 display resolution. As the number of colors increases 
per pixel, the quality, or reproduction of the original becomes better. 

With the advent of faster hardware, more and more software written for the 
PC is taking advantage of digital video technologies. Over the years, there has 
been many obstacles to the wide-spread usage of video playback on a personal 
computer. CPU speed, memory, hard drive size, and content distribution media 
large enough and cheap enough to hold the data, are all factors to consider. 
The CPU must provide enough processing power to handle digital video data in 
real time. This means that the computer can display at least 15 video frames 
in one second. And the computer still has enough processing power left for the 
operating system and application to handle user interactions. 

A large percentage of computers in use today are fast enough, meaning they 
have an Intel 386 or 486 compatible processor. They have enough hard drive 
space or a CD-ROM device, to be able to play movies at a decent frame rate of 
at least 15 frames per second. In addition, the acceptance of the CD-ROM as a 
distribution media has greatly facilitated the use of multimedia on personal 
computers, since, multimedia files tend to be quite large. For example, to store 
a full screen image of 640x480 pixels with 16-bits of color information would 
require 614400 bytes of space. Given this large size, the idea of compressing 
the data into a small size has become a method to reduce space requirements. 
The compression techniques used are becoming better and faster and this has 
caused the hardware storage requirements to shrink, reducing the cost 
considerably. 

As the hardware has progressed, the software for dealing with multimedia 
data has also progressed. The development of software-only decompression 
algorithms for both audio and video has helped to reduce the size requirements 
of multimedia data. The key of course, is that these are software only, so there 
is no need for special hardware to decompress the data. This allows any per¬ 
sonal computer with the right software and processing power to play multime¬ 
dia content. Since the majority of personal computers do not have expensive 
multimedia hardware for presenting data, like an IBM M-Motion video 
Adapter, software-only algorithms are the answer to video for the masses. 

Some decompression algorithms use hardware to assist or perform the 
decompression of digitized video, off loading the work from the main CPU. 
Some of these tend to be of motion picture quality. The software-only algo¬ 
rithms, on the other hand, are lower in quality, but can be utilized by the 
majority of personal computer equipment in use today—at a low cost. This is 
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one of the trade-offs when dealing with creating a multimedia application or 
multimedia content. A video or movie created to playback using software-only 
decompression is called a software motion video. A movie consists of not only 
video, but audio as well. To hear the audio, an audio device is required. 


DIGITAL VIDEO ON OS/2 


OS/2 version 2.1 and greater, including OS/2 for Windows, provide the ability 
to playback software motion videos. The ability to create and record movies 
was delivered in a product called Video IN. Several movie file formats, like 
AVI, FLC/FLI animation, and MPEG are supported. Several decompression 
types, like Ultimotion, Indeo 2.1, 3.1 and 3.2, FLC/FLI animation, and MPEG- 
1 are also supported. The OS/2 multimedia architecture allows new movie for¬ 
mats and decompression algorithms to be added easily. The list of supported 
movie file formats and decompressors will grow. The support for software 
motion video in OS/2 is provided by an MCI device called the digital video, or 
digitalvideo, device. 

The digitalvideo device is a media control driver, MCD, that provides ser¬ 
vices to play and record digital video. The video can be displayed in a default 
window provided by the digitalvideo device, or in an application supplied 
window. The device can provide playback of video in one of several ways 
depending on the type of data it is being requested to play. In the first case, 
video is played back and decompressed in software only. In the second case, the 
video is played back to a hardware adapter that decompresses the video in 
hardware and displays the video on a video overlay device. A video overlay 
device provides a hardware mechanism to display directly to a hardware moni¬ 
tor, by passing the internal computer display mechanism that software pro¬ 
grams typically use. This allows the video overlay hardware to control what is 
displayed on the screen. 

The digitalvideo device is almost misnamed; it really deals with movie cre¬ 
ation and playback, not just video creation and playback. It is a truly complex 
device because it combines two media types, namely audio and video. A movie 
consists of both video data and audio data. The digitalvideo device will take 
advantage of any OS/2 enabled audio hardware connected to the system to pre¬ 
sent the audio portion of the movie. The digitalvideo device also supports the 
Autodesk FLC/FLI animation file format for playback. In the latest version of 
OS/2, OS/2 3.0, the digitalvideo device will take advantage of graphic acceler¬ 
ator chipsets that allow clipping and continuous scaling to be done in 
hardware. 

The digitalvideo device support is broken up into two chapters. This chap¬ 
ter will discuss the general aspects of the digitalvideo device. It will mostly 
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discuss the fundamentals of the digital video devices that ship with OS/2 
Multimedia and the Video IN product. Topics such as software-only motion 
video, hardware assisted decompression, and support for hardware graphic 
acceleration will be discussed. There are multimedia extensions to the MCI 
interface that support M-Motion and ActionMedia II. The M-Motion Overlay 
and Amplifier/Mixer Device supports M-Motion, while the Digital Video 
Interactive Device supports the ActionMedia II Multimedia Adapter. These 
devices will not be discussed in this chapter. The Digital Video Capture chapter 
will discuss the record, capture, and overlay aspects of the digitalvideo 
device. 

This chapter will cover an overview of the digital video playback architec¬ 
ture followed by a detailed look at the high-level and low-level interfaces that 
can be used for digital video. The high-level interface consists of the digi¬ 
talvideo device MCI interface, which provides commands to set attributes, 
query information, perform device control and manage the video display win¬ 
dow. The low-level interface consists of a Direct Video Interface (DIVE) that 
facilitates fast direct access to the video frame buffer, as well as hardware 
independent access to hardware video acceleration. This chapter also includes 
a section that briefly describes some of the video CODECs available on OS/2 
today. 


DESCRIPTION OF VIDEO PLAYBACK ARCHITECTURE 


This section will describe at a high level, the architecture of the digitalvideo 
device. This will provide some insight as to how software motion video is 
played back. The underlying principle behind the digitalvideo device is the 
ability to play a movie for an application, that is, to do the work. It hides any 
movie file format and decompression specifics and isolates the application from 
hardware dependencies. The ability to easily playback and real-time record are 
built into the default digitalvideo device. Off-line recording, on the other 
hand, must be done by an application. The digitalvideo device provides some 
services to get images from video capture hardware. MMPM/2 provides a 
videodisc device to control a Laserdisc, but other then that, MMPM/2 does not 
become involved with off-line recording. 
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Digital Video Playback Architecture 
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Figure 6-1 . Digital Video Playback Architecture Diagram 


The digitalvideo device is actually a collection of several components in 
MMPM/2. The device fully utilizes the functionality of MMIO and the synchro¬ 
nization and streaming subsystem to perform its job of digital video device con¬ 
trol. The digitalvideo device connects these components in different ways 
depending on whether the device is setup to playback a movie or real-time 
record a movie. For all audio related functionality, the digitalvideo device 
uses the default or otherwise connected audio ampmix device. Typically when 
the digitalvideo device is opened either with a file name or not, it connects 
with the audio ampmix device if one is available. Once a movie file with audio 
is loaded, the audio ampmix device is initialized with the appropriate audio 
information. 

To open a movie file, the digitalvideo device uses the MMIO subsystem to 
isolate it from file format specific dependencies. The MMIO subsystem consists 
of an MMIO manager and a set of pluggable I/O procedures. Movie file formats 
are supported as pluggable I/O procedures. Refer to the Using Multimedia I/O 
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(MMIO) chapter for details on the MMIO subsystem and the supported file 
formats. 

The digitalvideo uses the mmioOpen and other APIs to identify the file 
format of the movie. The MMIO manager in conjunction with any movie file 
format I/O procedures installed in the system work together to identify and 
open the file. Once the file is opened, the digitalvideo device uses the 
mmioGetHeader API to query the file headers. The movie I/O procedure 
returns the file headers in standard presentation format—a file format-inde¬ 
pendent header format. At this point, the digitalvideo device determines 
whether a video and audio track exist in the movie file. 

During the file open process, the movie file format I/O procedure will load 
and initialize any digital video CODECs required to decompress the data in the 
video track of the file. CODECs are similar to file format I/O procedures in that 
they are pluggable procedures that provide services to compress and/or decom¬ 
press data. The Digital Video CODECs section at the end of this chapter lists 
the CODECs available and the Using Multimedia I/O (MMIO) chapter 
describes the CODEC architecture. All access to the CODECs are directed 
through the file format I/O procedure. This allows the digital video playback 
engine to transfer the data through the system in the native file format. The 
I/O procedure filters any file format specific information before passing the 
data to the CODEC to process. The I/O procedure is also able to pass additional 
information with each video frame like, frame number and frame type. 

The digitalvideo device only needs to be involved with the CODEC selec¬ 
tion process if it desires a different output format then the file format I/O pro¬ 
cedure chose when the file was opened. This output format is usually selected 
based on the current display mode. If the movie file contains compressed audio, 
the appropriate audio CODEC, if available, is loaded and initialized. 

Once the movie is open and the digitalvideo device has extracted the head¬ 
ers for all tracks of data, the digitalvideo device is ready to perform an opera¬ 
tion. Basically, there are three sets of operations: play, record, and edit. The 
record type operations will not be discussed in this chapter. 

For edit operations, the digitalvideo device mostly relies on the functionali¬ 
ty of the underlying movie I/O procedure loaded for this movie. Each movie 
type has an I/O procedure and not all I/O procedures support editing opera¬ 
tions. The AVI movie I/O procedure, and therefore the digitalvideo device, 
currently supports editing through the clipboard. It does not support editing 
through application provided buffers as the waveaudio device does. The 
MPEG and FLC/FLI file formats do not currently support editing or recording 
functionality. To support editing operations, it is necessary to have compres¬ 
sion capability, since depending on where the edit points are, two or more 
frames may need to be combined or altered to support the edit operation. The 
file format must also support writing or saving data to a file. 
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Play operations on the other hand, require much more setup and the func¬ 
tionality of the synchronization and streaming subsystem. The streaming sub¬ 
system consists of a stream manager and a set of data, or stream handlers. 
There exists a data handler for each type of media, e.g., audio and video. The 
streaming subsystem facilitates the transfer of data from device to device and 
provides a device independent mechanism to propagate synchronization infor¬ 
mation around the system. The streaming subsystem fully utilizes the pre¬ 
emptive multiple threaded nature of OS/2. Each of these stream handlers is 
run on a separate thread of execution. 

From the file headers, the digitalvideo device is able to determine which 
data handlers need to be loaded. For video data, the video stream handler is 
loaded. It handles the video data frames and controls the decompression, dis¬ 
play, synchronization with the audio stream, and event detection. It retrieves 
video frames from a queue of video buffers and passes them to the decompres¬ 
sor, via the file format I/O procedure. 

The decompressor may decompress the video frame directly to the video 
memory or to an output buffer. In the case of an output buffer, the video 
stream handler will call the Direct Interface Video Extensions (DIVE) display 
engine to display the output buffer to the screen. The display engine is a gener¬ 
al purpose engine used to display video to the screen efficiently. The display 
engine is discussed in more details later in this section. Any type of time 
events enabled for the digitalvideo device are handled by the video stream 
handler, since it controls the timing of each video frame display. 

For audio data, the digitalvideo device in combination with the audio 
ampmix device loads the audio stream handler. The audio stream handler 
retrieves audio data from a queue of audio buffers and passes the data to the 
appropriately connected audio device driver. The audio stream handler’s job is 
relatively simple compared to the video stream handler. The audio stream han¬ 
dler also has the ability to detect time events, but only when enabled through 
the waveaudio device. 

The third stream handler that is loaded by the digitalvideo device handles 
reading the data from the file format I/O procedure and filling the audio and 
video data queues or streams. This stream handler is called the multi-track 
stream handler since it, in conjunction with the file format I/O procedure, pars¬ 
es the file data into separate media based tracks of information. The video data 
is parsed into a list of video frames, while the audio data is parsed into a list of 
audio buffers. The audio buffers are then inserted into the audio queue and the 
video frames are inserted into the video queue. The audio and video stream 
handlers retrieve the data from the appropriate stream or queue. 

This process is optimized for data that is physically interleaved within the 
file. The MMIOM_MULTITRACKREAD message is used as the interface 
between the I/O procedure and the stream handler. The actual data is read 
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into a memory buffer and parsed by the file format I/O procedure, which passes 
lists of pointers to the individual data pieces to the multi-track stream handler. 
These pointers, not the actual data, are then inserted into one of the data 
streams. The stream manager manages the data pointers and data buffers so 
that reuse of buffers can occur. This mechanism provides an efficient way to 
transfer the data through the system without copying it. The actual data 
buffer, as filled by the file format I/O procedure ends up at the video decom¬ 
pressor or the audio device driver. 

The digitalvideo device sets up each stream and then starts them—this is 
how a movie is played on MMPM/2. The digitalvideo device coordinates 
between the stream handlers, file format I/O procedures, and CODECs to pre¬ 
sent an efficient and pluggable architecture for digital video playback. 

Video Playback Scalability 

Scalability is the ability to choose from a range of possible outcomes, one that 
best suits the needs of the system. In terms of video playback, scalability 
means the ability to scale up or scale down some attribute of the video so that 
the video can be played on a variety of hardware systems. Video under 
MMPM/2 can be scaled in three different ways: video resolution, frame rate, 
color space. These three attributes of video can be scaled up or down based on 
the speed of the microprocessor in the system, secondary storage device access 
times, and video display hardware. 

Video Resolution Scalability 

Video resolution is the width and the height of the video display. On OS/2 2.1 
versions of MMPM/2, some video compression types supported the ability to 
scale the video frame size to 1/2 or 2 times the size of the normal playback size. 
Not all CODECs supported this. On OS/2 3.0, the digitalvideo device uses the 
display engine to perform continuous scaling of the video frame to any size. 
This can either be done in hardware or software depending on the capability of 
the video display hardware. The video size can be stretched to full screen or 
shrunk to icon size. All CODECs that use the display engine can take advan¬ 
tage of this function. 

Frame Rate Scalability 

Frame rate scalability is the ability to vary the frame rate. For example, on 
slower machines the frame rate is scaled down to a slower frame rate and 
frames are dropped so that the video will play in sync with the audio. As the 
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video resolution is scaled up, typically, the frame rate is scaled down automati¬ 
cally by the digitalvideo device. This is because the larger frame sizes will 
consume more processor time to decompress and display on the screen. 

Color Space Scalability 

Color space scalability is the ability to display a 16-bit (64K colors) compressed 
video data on an 8-bit (256 colors) display. The display engine will automatical¬ 
ly scale the video color space to match the display mode. The display engine 
will also scale the video color space up to 24-bit display modes. It is recom¬ 
mended that at least an 8-bit display mode be used, since 4-bit (16 colors) pro¬ 
vides a very poor image quality. 

Color space conversion also includes the ability to convert between different 
color data representation formats. There are several formats in which the color 
data can be represented or encoded. Some hardware devices can handle the 
color information in certain formats. And some CODECs may only decompress 
to certain formats. The display engine provides the ability to convert between 
different types. This helps provide a level of hardware independence and frees 
CODECs from having to decompress data to more than one output format. 


THE DIGITAL VIDEO DEVICE INTERFACE 


The digitalvideo device can be controlled through the MCI interface. The dig¬ 
italvideo device provides services to play and real-time record digital video or 
movies. This chapter will discuss the commands that are common between the 
playback only and record enabled digital video devices. The Digital Video 
Capture chapter will discuss the record aspects of the digitalvideo device. 
These include real-time, frame-step record, and image bitmap capture from a 
playing movie or frame-grabber adapter. 

This section of the chapter contains detailed information on all playback 
related commands and some samples of their usage. Most of the samples are 
presented as simple MCI string interface commands. A few samples will use 
the procedural interface for lack of a string interface equivalent. As a rule, the 
MCI string interface should be used whenever it is possible, only use the proce¬ 
dural when it is required for some functions. This will make creating a multi- 
media application easier. 

The digital video device is of the device type digitalvideo. This is also the 
name of the default digital video device. In a system that has OS/2 multimedia 
installed with software motion video support, a digitalvideoOl device is pro¬ 
vided as the default digitalvideo device. You can reference it as digitalvideo 
or digitalvideoOl. The digitalvideoOl device can perform playback of video 
only, it does not require any special hardware to function. 
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If the system has the Video IN product installed, then in addition to the dig- 
italvideoOl device, a digitalvideo device will be provided for each hardware 
video capture adapter in the system. This depends on the install selections 
made by the end user of the system. These devices are named starting with 
digitalvideo02 and numbered sequentially. These “capture” digitalvideo 
devices can perform playback of video, real-time record of video, and bitmap 
capture from the hardware capture adapter. If there is any question about 
which digitalvideo devices can record, an application can use the capability 
command to ask the device. The capability command is described below. 

A user can make any digitalvideo device the default by using the 
Multimedia Setup Applet that ships with MMPM/2. An application can also 
change the default device by issuing an MCI_SYSINFO command message 
with the MCI_SYSINFO_SET_DEFAULT flag. In some cases it is necessary 
to change to default device for an application to work properly. Some applica¬ 
tions may expect the default device to be able to perform recording operations. 

Digital Video Commands 

All of the digitalvideo devices, whether they can playback video only, or play¬ 
back and record, support the following list of commands. Note that these com¬ 
mands may have additional functionality or give different results for digi¬ 
talvideo devices that can record. Some of these differences will be identified in 
this chapter and some in the Digital Video Capture chapter. 


Digital Video Device Commands: 


capability 

close 

connector 

copy 

cue 

cut 

delete 

info 

load 

open 

paste 


pause 

play 

put 

redo 

resume 

rewind 

save 

seek 

set 

setcuepoint 

setpositionadvise 


status 

step 

stop 

undo 

where 

window 


In addition to the previous set of commands, the following commands are 
supported by digitalvideo devices that can record or are attached to a hard¬ 
ware video capture adapter. They are not supported by the playback only digi¬ 
talvideo device (digitalvideoOl). 
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Digital Video Capture Device Commands: 

record 

settuner 

The MCI_GETIMAGEBUFFER command message is also supported, but 
only available through the MCI procedural interface. It is only supported on 
digitalvideo devices that can record or are attached to a hardware video cap¬ 
ture adapter. 

Digital Video Overlay Device Commands 

Currently, the video overlay specific commands are not supported by the 
digitalvideo device that ships with MMPM/2 or Video IN. Some other 
digitalvideo devices may support these commands. The following commands 
are not supported. 

Digital Video Overlay Device Commands: 

capture 

freeze 

restore 

unfreeze 

The video overlay commands are supported by the video overlay device for 
analog video. For example, the M-Control Program Version 2.01, which sup¬ 
ports the M-Motion Video Adapter/A, provides overlay extensions for OS/2 
Multimedia. 

Opening the Digital Video Device and Loading a Movie 

Before a digitalvideo device can be used, it must be opened with the open 
command. This command will return a device id that can be used to identify 
the instance of the digitalvideo device. All future references to this instance 
will require the device id. An alias can also be specified on the open com¬ 
mand, in this case, the alias can be used from the string interface to communi¬ 
cate with the device instance. 

A movie or video file can optionally be loaded on the open command. As a 
rule, whenever the file name is known at open time, it should be passed on the 
open. Otherwise, a movie file can be loaded into the device by using the load 
command. The digitalvideo device also has the ability to accept an MMIO file 
handle to an open file directly on either the MCI_OPEN or MCIJLOAD proce- 



236 


Developing Multimedia Applications Under OS/2 


dural commands if the MCI_OPEN_MMXO flag is used. This allows an appli¬ 
cation to open a memory file or manage the movie file directly. 

The open and load commands support the readonly keyword. This key¬ 
word indicates that the movie file should be opened in read-only mode, not 
read/write mode. This will increase performance of the open or load for a dig- 
italvideo devices that can record. Once a movie has been loaded and played, 
another movie can be loaded by using the load command. This is preferable to 
closing the digitalvideo device and re-opening it. 

The digitalvideo device is file format independent, which means that it 
will work with new file formats in the future. New file formats can be added by 
providing a file format I/O procedure. Refer to the Using Multimedia I/O 
(MMIO) chapter for a list of supported file formats and video decompression 
algorithms. 

Memory playlists are not support by the digitalvideo device. A playlist can 
handle data of one media type only (e.g., video or audio). Since the digi¬ 
talvideo device handles multiple media types, memory playlists can not be 
supported. An open or load of a non-existent file will succeed. This allows 
editing and record operations to easily create new file. When the empty file is 
played, it will fail. The load command also has a keyword, new, which can be 
used to indicate that a new file is being created. This is used by the editing 
operations or real-time record. 

The following are examples of digitalvideo open and load command 
requests: 


“open digitalvideo alias a wait “ 

“open digitalvideoOl notify “ 

“open e:\mmos2\movies\macaw.avi alias a notify “ 
“open digitalvideo alias a shareable notify “ 

“load a e:\mmos2\movies\macaw.avi notify “ 

“load a e:\mmos2\movies\macaw.avi readonly notify “ 


The digitalvideo device is opened in exclusive mode by default. To change 
this behavior, open the device as shareable. Conceptually, there is no real 
limit to the number of digitalvideo device instances that can be opened. The 
only thing that will limit the number that can be opened is the maximum num¬ 
ber of data streams and the amount of memory in the system. Each digi¬ 
talvideo instance uses a varying amount of memory to stream the movie data 
from the source to the display. A maximum number of data streams can be cre¬ 
ated at one time. This value can be increased or decreased to suit the needs of 
the user. Refer to the MMPM/2 Tips and Techniques chapter for more details 
changing the maximum number of streams. The processing power available 
will not limit the number of movies that can be played at the same time, but 
the playback of several movies on a slower machine (386), will not look great. 
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Digitalvideo devices that utilize hardware assisted decompression of the 
video data will support serially sharable contexts. This means that the device 
can be opened multiple times, but only one instance of this device will be active 
at a time. This is similar to the digitalvideo devices for video capture 
adapters. This sharing characteristic will vary according to the hardware. This 
is the case with MPEG movie playback on the Reel Magic video overlay 
adapter. The Reel Magic adapter also decompresses the MPEG audio for these 
movies, so the digitalvideo device will connect to the Reel Magic audio amp- 
mix device to play the audio portion of the movie. Currently, MPEG movies 
will only play on a specific digitalvideo device that defaults to the appropriate 
hardware device. In other words, MPEG movies can not be played on the digi¬ 
tal videoOl device. 

You can improve the application responsiveness by using the notify key¬ 
word on commands like open instead of the wait keyword. This will make the 
operation asynchronous. The MCI interface and digitalvideo device will 
acknowledge the command request and initiate the request using a separate 
thread of control. The application’s thread will return to the application, allow¬ 
ing the application to perform other actions while the asynchronous command 
executes. MMPM/2 and the digitalvideo device will notify the application 
asynchronously when the operation is completed with a MM_MCINOTIFY 
PM notification message to the applications window procedure. Note that it is 
important to take advantage of the asynchronous nature of most MCI com¬ 
mands. This can make your application more responsive to user input and 
other applications running on the system. It is always bad to have an applica¬ 
tion put up the timer cursor, but not let user switch to another session while 
the setup is being done. 

The digitalvideo device provides two methods of displaying the video for a 
movie: a default window or an application supplied window. For a default win¬ 
dow, the digitalvideo device creates and maintains a default video display 
window. In this case, an application issued open command may pass a parent 
window handle to be used as the parent window of the default video display 
window. This is the only window-related parameter that can be specified using 
the MCI interface that changes the behavior of the default video window. The 
digitalvideo device provides some basic services for default window control 
with the window command. Refer to the Video Display Window and Window 
Management Commands section in this chapter for details on this topic. 

The video display window will not appear until the digitalvideo device has 
been opened, a movie has been loaded, and one of the following commands is 
issued: cue, window state show, or play. Each of these commands is dis¬ 
cussed later in this chapter. 
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“cue digitalvideo output notify” 
“window digitalvideo state show wait 
“play digitalvideo notify” 


The close command can be used to close a device context, data element, and 
any other resource associated with the device. This command can be issued 
when the device is in almost any state. 

The Capabilities of a Digital Video Device 

The capability command should be used to query the capabilities of a device 
instance. This command can provide information on a variety of things, for 
example, whether an instance can record video or only playback video. Another 
example is whether an overlay hardware card is attached to the digitalvideo 
device that can provide TV tuning functionality. 


“open digitalvideo02 alias a notify” 

“capability a can record wait ” /* Returns TRUE if can record */ 

“capability a has tuner wait ” /* Returns TRUE if tuner hw */ 


The following list of capabilities is static. In other words the digitalvideo 
device will always return the return value listed. Any other capability not list 
in one of these following tables will result in an error return of 

MCIERR_INVALID_FLAG. 


Static Capabilites Keywords: 

compound device 
can play 
has video 
uses files 

can eject 
can lockeject 

can process internal 


Returns TRUE. The device is a compound device. 

Returns TRUE. The device can play. 

Returns TRUE. The device deals with video data. 

Returns TRUE. The element used with this device 
is a file path name. The device uses files. 

Returns FALSE. The device has no eject ability. 

Returns FALSE. The device can not disable manu¬ 
al eject of the media. 

Returns FALSE. The device has no DAC. 
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can record insert Returns FALSE. The device can not insert data 

into a file during record. 

has image Returns FALSE. The device supports image 

commands. 

device type Returns digital video. This capability returns the 

device type. 

preroll time Returns 0. The preroll time for the device is not 

bounded. 

preroll type Returns notified. The preroll characteristic of this 

device. 

can stream Returns TRUE. The device can digitally stream 

data. 

overlay graphics Returns FALSE. The device does not support 

graphics overlay over the digital video playback in 
the graphics buffer. 

can reverse The device returns FALSE, but it does play in 

reverse. Only I-frames are displayed. Refer to the 
Seeking a Movie section.* 

maximum play rate The device will return the error 

MCIERR_UNSUPPORTED_FLAG. 

minimum play rate The device will return the error 

MCIERRJJNSUPPORTED_FLAG. 

windows The device will return the error 

MCIERR_UNSUPPORTED_FLAG. 

The following capabilities can be dynamically set by the digitalvideo device 
depending on whether is has the corresponding functionality: 
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Dynamic Capabilities Keywords: 


has audio Returns TRUE if this device is connected to an 

audio ampmix device that will be able to play audio. 

can record Returns TRUE if this device is attached to video 

capture hardware. 

can save* Returns TRUE if this device is attached to video 

capture hardware. *Save works for video only, not 
image. 

can stretch Returns TRUE if the device frame-grabber type 

hardware is capable of performing scaling, such as 
Video Blaster. 

can distort Returns TRUE if the device hardware can indepen¬ 

dently stretch the horizontal and vertical dimen¬ 
sions of the image. 

normal play rate Returns the normal playback rate of the currently 

loaded file element, in the current speed format of 
percentage or FPS. 

fast play rate Returns 2x the normal playback rate of the current¬ 

ly loaded file element, in the current speed format 
of percentage or FPS. 

slow play rate Returns l/2x the normal playback rate of the cur¬ 

rently loaded file element, in the current speed for¬ 
mat of percentage or FPS. 

horizontal video extent If the device is attached to video capture hardware, 

the device will return the X source extent for the 
video source, otherwise, the device will return the 
error MCIERR_UNSUPPORTED_FLAG. 

vertical video extent If the device is attached to video capture hardware, 

the device will return the Y source extent for the 
video source, otherwise, the device will return the 
error MCIERR_UNSUPPORTED_FLAG. 

horizontal image extent If the device is attached to video capture hardware, 

the device will return the X source extent for the 
images, otherwise, the device will return the error 

MCIERR_UNSUPPORTED_FLAG. 
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vertical image extent If the device is attached to video capture hardware, 

the device will return the Y source extent for the 
images, otherwise, the device will return the error 

MCIERR_UNSUPPORTED_FLAG. 

If the device is attached to hardware that has TV 
tuning ability (e.g., Win/TV), TRUE is returned. 

If the device is attached to hardware that has TV 
automatic frequency control (e.g., Win/TV), TRUE 
is returned. The digitalvideo device does not sup¬ 
port afc functionality. 

If the device is attached to hardware that has TV 
teletex support (e.g., Win/TV), TRUE is returned. 
The digitalvideo device does not support teletex 
functionality. 

If the device supports the xxx message, the TRUE 
is returned. 

** New for OS /2 version 3.0 

Audio related capabilities are queried from the audio ampmix device if one 
is attached to this digitalvideo device instance. These include the following 
capabilities: 

Audio Ampmix Capability: 

can setvolume The audio ampmix device will return TRUE if the 

audio device supports software control of volume 
level. 


Audio Device Connection for Movie Playback 

When a digitalvideo device is opened for playback, the digitalvideo device 
connects to the default audio ampmix device. This happens automatically 
within the digitalvideo device, before the data element is loaded; even if the 
digitalvideo device will be used to play a video only file. This tends to tie up 
the audio ampmix device from being used by another device, at least if the 
digitalvideo device is opened as exclusive. Currently, there is no way for an 
application to prevent this. 


has tuner ** 
has afc ** 

has teletex ** 

message xxx 
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If a digitalvideo device is opened with a movie that has audio, but there is 
not audio ampmix device installed in the system, the movie will play without 
audio. Also, if when the digitalvideo device is opened, there is an audio amp- 
mix, but another device has acquired it exclusively, movies loaded into this 
device instance will play without the audio portion. 

The audio ampmix device that the digitalvideo device will use is specified 
in the MMPM2.INI file entry for the digitalvideo device. The ampmix device 
can be changed permanently by using the MCI_SYSINFO command message 
with the MCI_SYSINFO_SET_CONNECTORS action flag. This is not recom¬ 
mended, because applications using the digitalvideo device would be affected 
by this change. A better way is to make a connection to an alternative amp¬ 
mix device for an instance of a digitalvideo device. The default ampmix 
device connection will first need to be “broken” and the alternate ampmix 
device connection “made.” 

To change the digitalvideo default ampmix device connection for playing 
on a different audio card, use the defaultconnection command. This is also 
useful when trying to open multiple digitalvideo devices at the same time to 
play multiple movies at the same time. If there is more than one audio amp¬ 
mix device in the system, the audio for each movie could be sent to a different 
audio ampmix device. In the sample that follows, the first movie audio will 
play in the default ampmix device, ampmixOl, and the second movie audio 
will play on the ampmix02 device. 


“open digitalvideo 
“defaultconnection 
stream wait” 
“defaultconnection 
stream wait” 

“open digitalvideo 


alias dvl shareable notify” 

digitalvideo break type wave stream to ampmixOl totype amp 
digitalvideo make type wave stream to ampmix02 totype amp 
alias dv2 shareable notify” 


Currently, if two movies both have mono audio data streams and the audio 
ampmix device installed in the system can play two mono data streams at the 
same time, the audio for both movies will be heard. 

Another useful function is the ability to query the ampmix device connected 
to a digitalvideo device instance. This will allow the application to communi¬ 
cation directly with the ampmix device. For example, the balance of the 
audio can be changed to 100, full right, for the audio ampmix device connected 
to the digitalvideo device. The connection command can be used to set an 
alias for the ampmix device connected to the digitalvideo device. Using this 
alias, audio related attributes can be changed. Some audio attributes can be 
set directly through the digitalvideo device, for example, volume. 
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“open digitalvideo alias dv notify” 

“load dv e:\mmos2\movies\macaw.avi notify” 

“connection dv query type wave stream number 1 alias am wait” 

“set am balance 100 wait” 

The connector command can be used to query or change an audio related 
connection, or to query or change the video in connector type. The number 
keyword must be specified with a type keyword, or it will fail for the digi¬ 
talvideo device. The following are valid connector types for digital video. Note 
that the audio related connector types are routed to the audio ampmix device. 

connector type: 

line in (audio) 

line out (audio) 

audio in (audio) 

audio out (audio) 

microphone (audio) 

speakers (audio) 

headphones (audio) 

video in (Only valid for a recording digitalvideo device) 

wave stream (queried only, digitalvideo always returns TRUE) 

Querying Digital Video Device Information 

The info command will return string information about the digitalvideo 
device. The following is the list of supported info commands: 

file Returns the currently opened file name. This command 

will return file not found error if no file is currently 
loaded into the digitalvideo device instance. 

product Returns the product name of the digitalvideo device. 

This information is queried from the MMPM.INI file. 

window text Returns the video display window title bar text. The dig¬ 

italvideo sets the title initially to the name of the 
decompression CODEC used for the data element. 
However, the title bar text can be changed in the default 
window by using the window text command. This com¬ 
mand will return file not found error if no file is current¬ 
ly loaded into the digitalvideo device instance. 
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region** Returns the text abbreviation for the geographic region 

of the world that is currently enabled for the TV tuning 
functionality. This function is available on digitalvideo 
devices that are attached to the appropriate hardware 
(e.g., Win/TV video capture adapter). 

region text** Returns the text description for the geographic region of 

the world that is currently enabled for the TV tuning 
functionality. This function is available on digitalvideo 
devices that are attached to the appropriate hardware 
(e.g., Win/TV video capture adapter). 

** New for OS/2 version 3.0 

The following samples shows the proper usage: 


“open digitalvideo alias a wait” 
“info a product wait” 


Cueing the Digital Video Device 

The cue command is an optional command that can be used by an application 
to set up the digitalvideo device to play or record. The cue command with 
the output keyword indicates that the digitalvideo device should prepare for 
a play command. The cue command with the input keyword indicates the 
digitalvideo device should be prepared for real-time recording. The cue for 
input is only supported on digitalvideo devices that have video capture hard¬ 
ware attached. 

This command allocates the stream buffers for either the playback or record 
scenario. It also pre-fills the buffers with data so that when a play or record 
command is issued by the application, it will occur in a minimal amount of 
time. This is especially important for record, if recording from a manually 
operated device like a VCR. It is desirable for the recording to actually start to 
capture data as soon after the record command is sent as possible. On a play 
command, if no cue request has been processed for the device, an implicit cue 
will occur at this point. This guarantees that the streaming buffers are pre¬ 
filled. This will maximize the ability to synchronize the audio and video output 
when the play actually begins. This implicit cue will occur when the device is 
in a stopped (not paused) and has not already been cued. A slight delay in the 
playback output may occur, especially when reading from a slow secondary 
storage device like a CD-ROM. To minimize the delay, always cue first. The 
following is an example of cue: 
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“open e:\mmos2\movies\macaw.avi alias a notify” 
“cue a output notify” 


Playing a Movie 

Two commands that will cause the digitalvideo device to play the movie or 
display video frames from the movie are: play and step. 

Play Command 

The play command issued without any additional keywords will play from the 
current position to the end of the movie. If the from keyword is used on the 
play, the play command will perform an implicit seek operation to the correct 
position before playing to the end of the movie. The to keyword can also option¬ 
ally be specified to select an endpoint for the play operation. In regards to the 
from keyword, refer to the Seeking a Movie section of this chapter for a discus¬ 
sion of the seek granularity. The to position is exact. Both of these keywords 
can be use together or with the other play rate and direction modifier key¬ 
words, reverse, scan, fast, slow, and speed. The to and from parameters 
must be specified in the current time format. 

reverse The reverse indicates that the movies should be played 

in reverse. When playing in reverse, only the I-frames 
(refer to the Seeking a Movie section) are displayed, but 
the digitalvideo device tries to play these frames at 5 
times the normal frame rate of the movie. No audio is 
played in this mode. 

scan The scan keyword indicates that only the I-Frames 

should be displayed from the movie. The digitalvideo 
device will attempt to display these frames at 5 times the 
normal movie frame rate. No audio is played in this 
mode. 

fast The fast keyword indicates that the digitalvideo device 

should attempt to play the movie at twice the frame rate 
the movie would normally play at. No audio is played in 
this mode. 

The slow keyword indicates that the digitalvideo 
device will play the movie at one half the frame rate the 
movie would normally play at. No audio is played in this 
mode. 


slow 
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speed The speed keyword indicates that the movie should play 

at the rate specified. The rate can be given in any of the 
units supported by the set speed format command. If 
the speed given equals the normal frame rate, then audio 
is played with the video, otherwise, no audio is played. 

When a movie is opened or loaded, the current position is set to 0. Each 
video frame in a movie file has a number associated with it. The digitalvideo 
device views all movies as being zero-based. That is, the first frame of a movie 
is frame 0, and the second is frame 1. Therefore, the last frame of the movie file 
is the total length of the movie, in terms of frames, minus one. The current 
position always indicates the frame that is about to be displayed, rather than 
the frame that is currently displayed. 

The notify keyword should be used with the play command. This will allow 
the application to interrupt the play operation with another command, like 
stop using the same application thread. Otherwise, a separate thread will be 
required to stop the play if the wait keyword was used. 


“play a wait” 

“play a from 3000 to 6000 notify” 
“play a fast notify” 

“play a reverse from 1000 notify” 


Step Command 

The step command directs the digitalvideo device to display one video frame 
from the movie, by skipping over 0 or more video frames. A step by 1 is equiv¬ 
alent to doing a play to the next frame. A step by 5 is equivalent to doing a 
relative seek ahead by 4 video frames and displaying the next frame, essen¬ 
tially, moving by 5 frames. A step reverse by 1 is equivalent to doing a rela¬ 
tive seek backwards by 2 frames and displaying the next frame, essentially, 
moving backwards 1 frame. 


HINT: Step by 1 (frame) can be used to display the first frame after loading a movie. 
This is useful to applications that may load a movie and display the video playback 
window, but not play the movie immediately. 


“step a by 1 wait” 

“step a by 10 notify” 

“step a reverse by 15 wait 
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Playing AVI Movies Created on Other Operating Systems 

This is a list of things to consider when playing or recording AVI movies that 
will be used on multiple operating systems. The AVI file format is short for the 
Audio/Video Interleaved file format. It is a standard movie file format used on 
both the OS/2 and Windows operating systems. AVI files can contain multiple 
streams, or tracks of data. These tracks include audio, video, text, and other 
data types. Refer to the Using Multimedia I/O (MMIO) chapter for more 
details on the AVI file format. 

1. There may be loss of synchronization between audio and video on AVI 
movies created on platforms other than OS/2. Sometimes the frame rate 
at which the movie was created is not exactly frame rate, for example, 15 
frames per second. The audio and video in these movies will not stay in 
sync throughout the play. This problem can be corrected by editing the 
movie. First, strip the audio out of the movie using the AVI file utility, 
then insert duplicate video frames throughout the movie. These duplicate 
video frames can be created by using the editing commands to copy a 
frame to the clipboard and pasting it back into the movie. The AVI file 
utility can display the frame rate, and from this it should be possible to 
determine how many frames to insert. Finally, merge the audio data back 
into the movie file. This process can be done by using the AVI file utility 
program and the software video recorder applet shipped in the Video IN 
product. 

2. For AVI movie file, the streams can be interleaved to improve access 
times during playback. The file can be interleaved 1-to-l; that is, one 
video frame followed by one “chunk” of audio. The audio “chunk” is equiv¬ 
alent in time to the one video frame. AVI movie files do not need to be 
interleaved 1-to-l to be played on OS/2, but they can be interleaved at any 
rate. Some AVI files created under Video For Windows put all of the 
audio at the end of the AVI movie file, in effect not interleaving the file. 
To play these files on OS/2, it is necessary to use the AVI file utility to 
interleave the audio and video streams. The interleaving is not required 
to be 1-to-l. 

3. Some audio adapters can not play movie files that are interleaved 1-to-l 
very well because of the small audio “chunk” sizes. If you experience con¬ 
tinuous audio breakup on these types of movies, it may be necessary to 
use the AVI file utility program to re-interleave the movie file at a differ¬ 
ent ratio of video frames to audio “chunks.” For example, a 5-to-l ratio 
should be more than adequate. 
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4. Some Indeo 2.1 AVI movies will not play on the OS/2 2.1 version of 
MMPM/2. The FOURCC for the compressor is incorrect. This can be cor¬ 
rected by editing the movie with a binary editor and replacing any “rt21” 
strings with “RT21.” This is not a problem on the OS/2 2.11 or OS/2 Warp 
versions. 

5. MMPM/2 does not currently support playing certain audio tracks within a 
multiple audio track AVI files. MMPM/2 will only play the first audio 
track in the movie. 

Stopping, Pausing , and Resuming a Movie 

The digitalvideo device supports the standard control commands stop, 
pause, and resume. The stop command is used to abort a play operation or 
stop a record operation. The pause command is used pause the current play 
or record operation. In the case of the pause command, the play or record 
operation is not aborted. It can be restarted by using the resume command. 
The play command will also perform a resume operation if restarting a 
paused play command. This also applies to the record command. 

It is important to understand the difference between the stop and pause 
command. During a stop operation of a play command, the current set of 
streaming buffers is discarded and the play is aborted. To restart the play 
involves refilling the streaming buffers. This is an implicit cue being done 
within the play command. A stop of a record operation will flush the data in 
the streaming buffers out to the file that is the target of the record. Both the 
discard and flush type stops are asynchronous operations by nature within the 
digitalvideo device. Therefore, it is more efficient to use the notify keyword 
on a stop operation. A pause command on the other hand, is a synchronous 
operation by nature within the digitalvideo device. The pause command will 
not discard or flush the contents of the stream buffers. When the play or 
record is resumed, the streaming buffers contain the same data and do not 
need to be refilled. Therefore, a pause is quicker and more efficient then a 
stop. Always use a pause unless trying to abort the play or record operation. 


“pause digitalvideo wait” 
“stop digitalvideo notify” 
“resume digitalvideo wait” 
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Seeking a Movie 

The digitalvideo device supports the standard command to perform position 
changes within a movie called seek. The digitalvideo device also supports a 
specialized seek called rewind that performs a seek to start operation. The 
seek command to parameter must be specified in the current time format 
selected. Seek to end and seek to start are supported as well. 

The seek and rewind commands perform an implicit stop operation if the 
digitalvideo device is currently not already in a stopped state. This invali¬ 
dates the streaming buffers before the seek occurs. Because after the seek is 
performed, the contents of the buffers would be invalid because of the new file 
position within the movie file. Seek commands can take a relatively long peri¬ 
od of time, especially if performing a seek on a CD-ROM device, so the notify 
keyword should be used. 

I-frames An Intracoded frame or I-frame contains a complete 

video image, when decompressed, with no dependencies 
on any previous frames. It can be decompressed without 
any other video frames. This is sometimes called a refer¬ 
ence or key frame. A typical video will contain both I- 
frames and delta frames. 

delta frame A delta frame is a video frame that contains partial 

information. It will usually require a set of frames pre¬ 
ceding it to provide part of the complete frame image. 
Since a delta frame is only a partial frame, it contains 
less information than an 1-frame and can be compressed 
into a smaller space. It will also require less time to be 
decompressed. 

I-frame Interval Typically, a video has an I-frame interspersed within a 
sequence of delta frames. For example, a standard rate 
for Ultimotion is an I-frame every 2 seconds. At 15 
frames per second, every 30th frame is an I-frame. All of 
the rest of the video frames would be delta frames. The 
I-frame interval is selectable by an application at video 
capture time. The set reference frame interval com¬ 
mand is used to set this value. 

If the nearest keyword is specified on the seek command, then the seek is 
performed to the nearest I-frame preceding the position requested. Some file 
format and compression types have only one I-frame within a movie file, there- 
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fore, seeks to the nearest I-frames will always seek to the first frame in the 
file. FLC/FLI animation files are an example of this. A seek on a FLC/FLI file 
will always seek to the start of the file. As the number of I-frames in a file 
goes down, the granularity of the seek nearest goes down and seek time may 
go up. For file formats that support precise seeking, the play start time goes 
up as well. This is a trade off when creating movie files, because I-frames tend 
to be more expensive to decompress and typically take up more space, so the 
fewer the I-frames, the more efficient and smaller the file will become. 

Seeking to the I-frame provides a faster play command start time then a 
seek to a delta frame. When seeking to a delta frame, the digital video device 
will seek to the previous I-frame and return. When the next play command is 
issued, the digitalvideo device will decompress the I-frame and all frames up 
to the seek point but not display the output image. It remembers the original 
seek position request and skips the display of frames until the correct frame is 
decompressed. At this point, the video is display. This process may cause a 
slight delay after a seek. This delay will go up as the number of I-frames in 
the file goes down. 


“rewind digitalvideo notify” 

“seek digitalvideo to start notify” 

“seek digitalvideo to 0 notify” 

“seek digitalvideo to end notify” 

“seek digitalvideo to 3000 notify” 

“seek digitalvideo to nearest 3000 notify” 


Setting Cuepoints and Position Advise Events 

The digitalvideo device supports two commands to enable and disable time- 
based or position-based event notifications. These event notification commands 
are setcuepoint and setpositionadvise. The position parameters used on 
both commands must use the current time format. The first difference 
between the two commands is that a cuepoint is a one-time event and a posi¬ 
tion advise is a recurring event that is based on a time interval. The second 
difference is that the digitalvideo device can enable multiple cuepoints, but 
only one position advise can be enabled at a time. 

Each enabled cuepoint requires memory and processing time. Once a cue- 
point is enabled, it remains enabled until the application disables the cuepoint. 
If a movie is played and then seeked to the start, the same cuepoint, if not dis¬ 
abled, will be triggered again by each subsequent play. An application should 
always disable a cuepoint once it is no longer needed. 

The digitalvideo device has a limit as to the number of cuepoints that can 
be enabled at one time. One way to minimize the number of enabled cuepoints 
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is to disable cuepoints as they are reached. Another point of interest is that 
cuepoint and position advise granularity is based on the hardware and operat¬ 
ing system capability. The minimum granularity for a cuepoint and position 
advise is one frame time duration. Events are typically processed once per 
video frame display. Of course, as the frame rate increases, the frame duration 
decreases and so does the event granularity. 


“setcuepoint digitalvideo on at 12000 return 100 notify” 
“setcuepoint digital video off at 12000 notify” 

“setpositionadvise digital video on every 9000 notify” 
“setpositionadvise digital video off notify” 


Querying Device Status 

The digitalvideo device provides a command, status, to query information 
about the current state of the device. This information is similar to the capa¬ 
bility command, but it is different in that this command returns information 
based on the currently load file. It also returns the current state or value of 
some of the set command operations. The supported status keywords are list¬ 
ed in a series of tables that are grouped by device. The first table shows gener¬ 
al status keywords, while the second table shows audio ampmix device relat¬ 
ed commands. The audio related keywords can be used on the digitalvideo 
device, but they are routed to the connected ampmix device. The third table 
shows the digitalvideo record device only status keywords. These are valid 
for digitalvideo devices that are attached to video hardware. 

General Status Keywords: 

audiosync Returns the audio synchronization adjust value. This 

value is always expressed in MMTIME units. This 
default value is 0. 

audiosync direction Returns the direction of the adjustment in audio syn¬ 
chronization, meaning forward or backwards relative to 
video time. The default is forward. 

clipboard Returns TRUE if digital video/movie data is in the clip¬ 

board. Otherwise, FALSE is returned. 

current track This keyword combination is not supported. 

droppedframepct Returns the percentage of dropped frames. Refer to the 
Audio and Video Synchronization section of this chapter 
for more details. 
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vertical image 
extent 

forward 

horizontal video 
extent 

length 

length track xx 
media present 
mode 

normal rate 

number of tracks 

paste 

position 

ready 

redo 

speed 

speed format 
time format 
undo 

horizontal image 
extent 


This keyword combination is not supported. 


Returns TRUE if the play direction is forward or if 
the device is not playing. 

Returns the horizontal extent of the currently loaded 
movie. 

Returns the length of the movie in the current time for¬ 
mat. 

This keyword combination is not supported. 

Returns TRUE. 

Returns the current device mode: not ready, pause, 
play, record, seek, stop. 

Returns the normal playback rate of the currently loaded 
movie. The value is returned in the current speed for¬ 
mat. 

Returns the number of tracks in the currently loaded 
movie. 

Returns TRUE if digital video/movie data is in the clip¬ 
board and can be pasted. Otherwise, FALSE is returned. 

Returns the current position of the movie in the current 

time format. 

Returns TRUE if the digitalvideo device is in the ready 
mode. 

Returns TRUE if a redo operation can be performed. 
Otherwise, FALSE is returned. 

Returns the frame rate of currently loaded movie in the 
current speed format. 

Returns the current speed format. 

Returns the current time format. 

Returns TRUE if a undo operation can be performed. 
Otherwise, FALSE is returned. 

This keyword combination is not supported. 
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vertical video 
extent 

Returns the vertical extent of the currently loaded movie. 

window handle 

Returns the window handle for the video display 
window. 

Audio Related Status Keywords: 

bitspersample 

Returns the currently set bits per sample used for play¬ 
ing, recording, and saving. 

channels 

Returns the currently set channel count used for playing, 
recording, and saving. 

format tag 

Returns the currently set format tag. Not all audio for¬ 
mats are supported for record. 

samplespersec 

Returns the currently set samples per second used for 
playing, recording, and saving. 

volume 

Returns the currently set volume. 

Digital Video Record/Overlay Device Only Status Keywords: 

brightness 

Returns the brightness level. 

contrast 

Returns the contrast level. 

hue 

Returns the hue level. 

monitor 

Returns the current state of the video monitor window: 
ON or OFF. 

monitor window 
handle 

Returns the window handle for the video monitor 
window. 

record audio 

Returns TRUE if the device is setup to real-time record 
audio. 

reference frame 
interval 

Returns the reference frame (I-frame) interval for the 
currently loaded movie. The default is 15 fps. 

saturation 

Returns the saturation level. 

sharpness 

Returns the sharpness level. 

transparent color 

Returns the value of the transparent color used on 
video overlay hardware. 
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video compression 

video compression 
subtype 

video record rate 

video record 
frame duration 

video quality 


Returns the record compression type FOURCC. 

This keyword combination is not supported. 

Returns the record rate setting. 

Returns the record frame duration setting. 

Returns the record video quality setting. The default is 
5000. 


image bitsperpel Returns the number of bits per pel for saving bitmaps, 

image pelformat Returns the pel format for saving bitmaps or images. 


Setting Device Controls and Attributes 

The set command provides a way of setting device specific attributes. Some of 
these are related to the currently loaded file and some are specific controls for 
any video hardware that is attached to the device. The valid set keywords are 
shown in a series of tables similar to the way the status keywords are shown. 
However, there are two additional tables. One shows the valid time formats 
and the other the valid speed formats for the digital video device. The other 
three tables show the general digital video device set operations, audio relat¬ 
ed set operations, and the set operations for video record or overlay devices. 
Most of these set operations can not be performed while the device is recording 
or cued for recording. If a digitalvideo device is not connected to an audio 
ampmix device, that is, no audio hardware or audio device is being used by 
another device, then the audio set operations will return the 
MCIERR_NO_AUDIO_SUPPORT error. 


General Set Keywords: 

audiosync xx 


audiosync xx 
forward 


audiosync xx 
reverse 


Sets the audio synchronization value, where xx is the 
MMTIME value to adjust audio time ahead relative to 
video time. 

Sets the audio synchronization value, where xx is the 
MMTIME value to adjust audio time ahead relative to 
video time. 

Sets the audio synchronization value, where xx is the 
MMTIME value to adjust audio time back relative to 
video time. 
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Time Format Set Keywords: 

time format ms * Sets the time format to milliseconds. The keyword 
milliseconds can also be used. If set, all positional 
information will use this format. 

time format Sets the time format to MMTIME or 1/3000 of second. 

mmtime * If set, all positional information will use this format. 

This is the default time format. 

time format Sets the time format to frames. If set, all positional 

frames * information will use this format. 

time format hms * Sets the time format to hours:minutes:seconds If set, 
all positional information will use this format. 

time format hmsf * Sets the time format to hours:minutes:seconds:frames. 

If set, all positional information will use this format. 

* Can be set during record. 

Speed Formats Set Keywords: 

percentage * Sets the playback speed format to a percentage of the 

normal playback rate of a movie. 

fps * Sets the playback speed format to frames per second. 

This is the default speed format. 

* Can be set during record. 

Audio Related Set Keywords: 

alignment xx Sets the block alignment of audio data in bytes, where 

xx is number of bytes. 

audio all xx Enables or disables both channels of audio for recording 

or playing, where xx is on or off. 

audio left xx Enables or disables the left channel of audio for record¬ 

ing or playing, where xx is on or off. 

audio right xx Enables or disables the right channel of audio for 
recording or playing, where xx is on or off. 

audio over xx Fades audio over the period of time specified, where xx 

is in milliseconds. 
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audio volume xx Sets the audio volume level, where xx is a percentage. 

bitspersample xx Sets the bits per sample used for recording audio, where 
xx is the bits per sample. The default is 8. 

channels xx Sets the number of channels to use for recording audio, 

where xx is 1 or 2. This indicates mono (1) or stereo (2). 
The default is mono. 

format tag xx Sets the format tag used for recording audio, where xx 

is the format tag. The digitalvideo device does not 
support recording all types of audio. The default is 

WAVE_FORMAT_PCM. 

samplespersec xx Sets the samples per second used for recording audio, 
where xx is the samples per second value. The default is 

11025 . 

volume xx Sets the volume used for recording audio, where xx is 

the percentage in a range 0 to 100. 

Digital Video Record/Overlay Device Only Set Keywords: 

brightness xx * Sets the capture hardware brightness level, where xx is 
a value in the range 0 to 100. The default is set in the 
device setup or device driver default. 

contrast xx * Sets the capture hardware contrast level, where xx is a 

value in the range 0 to 100 . The default is set in the 
device setup or device driver default. 

hue xx * Sets the capture hardware hue level, where xx is a value 

in the range 0 to 100 . The default is set in the device 
setup or device driver default. 0 is maximum green and 
lOOis maximum red. 

monitor xx Sets the monitor video window on or off, where xx is on 

or off. Monitoring is done either in software or hardware 
if it is available. If the capture hardware has overlay 
capability, the monitor is done in hardware. The default 

if off. 

record audio xx Enables audio recording, where xx is on or off. The 
default is on. 
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reference frame 
interval xx 

Sets the reference frame interval for recording, where 
xx is the nth frame to insert an I-frame. The default is 15 
or one I-frame every 15th frame. The Video IN Software 
Video Recorder Applet sets this value to 30 as its default. 

saturation xx * 

Sets the capture hardware saturation level, where xx is 
a value in the range 0 to 100. The default is set in the 
device setup or device driver default. 

sharpness xx * 

Sets the capture hardware sharpness level, where xx is 
a value in the range 0 to 100. The default is set in the 
device setup or device driver default. 

transparent 
color xx 

Sets the transparent color used on video overlay 
hardware, where xx is in the range 0 to n-1. The number 
of colors is n. The default is set in the device setup or 
device driver default. 

video compression 

XX 

Sets the real-time recording compression type FOURCC. 
Refer to the table of supported CODECs the Digital 
Video CODECs section of this chapter for the list of valid 
CODECs provided with MMPM/2. Other CODECs can be 
installed in the system. 

video compression This keyword combination is not supported. 

subtype xx 

video record 
rate xx 

Sets the record frame rate, where xx is the frame rate in 
frames per second in a range 1 to 30. 

video record 
frame duration xx 

Sets the record frame duration, where xx is the frame 
duration in microseconds. This allows a non-integer 
frame rate to be set for record. The valid range is 33,333 
to 1,000,000. 

video quality xx 

Sets the record video quality setting, where xx is either 
a value in the range 0 to 10000, or it is one of the follow¬ 
ing keywords: low (0), medium (5000), high (10000). A 
video CODEC may not support this setting. To deter¬ 
mine if a CODEC does, refer to the Querying CODEC 
Procedure Information section of the Using Multimedia 
HO (MMIO) chapter. 


* Can be set during record. 
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Video Display Window and Window Management Commands 


The digitalvideo device displays all video from a movie in a window on the 
screen or if it is full screen, the whole screen space is utilized. The digi¬ 
talvideo device provides two methods of displaying the video for a movie: 

1. A default window, that is created and manipulated by the digitalvideo 
device. 

2. An application supplied window. This is a window provided to the digi¬ 
talvideo device by an application. This allows an application to control 
certain characteristics of the windows and placement of the window with¬ 
in the application. 

In both cases, the digitalvideo device confines its output to the device coor¬ 
dinates of the specified window. This is also true, whether the video is display 
by software or a hardware overlay device. The following picture depicts a typi¬ 
cal default video display window as viewed under OS/2 2.1. 



Figure 6-2. Digital Video Device Default Window 

Default Window 

The default window is used if the application does not provide a window han¬ 
dle through the window command. The parent of the default video window is 
HWND_DESKTOP unless otherwise specified in the MCI_OPEN command 
message. The owner of the default video window is NULL. An application can 
specify a parent window handle for the default video window using the 
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hwndParent field and the MCI_DGV_OPEN_PARENT flag when the device 
is opened. This is the only window-related parameter that can be specified 
using MCI commands that change the behavior of the default video window. 
The default window is sized to the size of the video. The digitalvideo device 
provides and manages this window for the application. On OS/2 Warp the win¬ 
dow can be continuously sized to any size including icon size. This is provided 
by the ability of the display engine to scale and stretch the video to any size (in 
software or hardware if supported). On OS/2 2.1, the window could be scaled to 
1/2 or 2 times the normal video size and only if the digital video CODEC sup¬ 
ported this functionality. 

The default video window is invisible when the digitalvideo device is first 
opened. This allows the application to prepare the size, position, and contents 
of the window before it is displayed. It is created in a frame window, which can 
be sized, moved, maximized, minimized. It is also created with an ideal aspect 
ratio in the center of the display and the size depends on the size of the video 
as it was captured. 

An application can set this by using the window handle default command 
to specify that the default window handle should be used for the playback or 
record monitor video display window. The other keywords for window like 
show and hide can only be used for the default playback window or the 
default monitor window if the monitor keyword is specified. The text keyword 
can only be used with the default playback window. 

Application Supplied Window 

An application supplied window can be used when the application requires 
more control over the video display window. The application can place video in 
its own client area or in a child window and add menus among other things. If 
an application specifies a parent window handle when opening the device, it 
must close the logical video device before destroying the parent window. The 
digitalvideo device subclasses the application’s window to receive any neces¬ 
sary notifications such as palette changes, clipping, sizing, and moving mes¬ 
sages from PM. 

An application can set this by using the window handle command to speci¬ 
fy the application window handle to use for the playback or record monitor 
video display window. The other window keywords can not be used with an 
application specified window. 

If an application passes a window handle to the digitalvideo device with 
the window command, it is essential that the application ensure that this win¬ 
dow will receive all WM_REALIZEPALETTE messages sent to the message 
queue. If the window is a client window (its parent has a style of CS_FRAME 
and the window has an ID of FID_CLIENT), or if it is the child of a client 
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window, it will receive this message automatically. If, however, the window 
has an ancestor that is not a client window and does not pass WM_REAL- 
IZEPALETTE to WinDefWindoivProcO , the window will not automatically 
receive the message. For example, WinDefDlgProcO does not pass 
WM_REALIZEPALETTE on to child windows. So, if an ancestor of the win¬ 
dow is a dialog window, the dialog procedure must explicitly pass the 
WM_REALIZEPALETTE message to the window. If the window does not 
receive this message, then incorrect colors will appear in video displayed in the 
window, whenever another application changes the system palette. 

Window Management Commands: 

The three window management commands are: window, where, and put. 
These commands are used to query and set window related information. The 
windowcommand is mostly used with the default playback and monitor win¬ 
dows, not the application specified window. The where command is used to 
query rectangle dimensions for the source or destination area. The put com¬ 
mand is used to specify the source and destination windows. It can be used to 
precisely position the video display window within the application’s window. 
The digitalvideo device must be cued or playing for the put command to take 
effect. The put destination command has the restriction in OS/2 2.1 that the 
xLeft and yBottom values of the destination must be zero. The keyword mon¬ 
itor can be used with any of the window commands, except text, to indicate 
that the record monitor window should be modified instead of the playback 
video display window. 

If the video display window is visible when the digitalvideo device alters 
the size and position of the video accordingly, the digitalvideo device will 
remember the changes. However, if the window size and position is changed 
while the window is hidden, the digitalvideo device will not remember the 
new size and position. 

Editing Movies 

The digitalvideo device supports the ability to edit movies. The editing opera¬ 
tions consist of the following commands: 

Editing Commands: 


Copies a movie or a section of a movie to the clipboard. 
The from and to keywords can be used with copy. If no 
from is specified, the current position is used. If the to is 
not specified, the end of file is used. 


copy 
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cut Copies a movie or a section a movie to the clipboard and 

deletes it from the current file. The from and to key¬ 
words can be used with cut. If no from is specified, the 
current position is used. If the to is not specified, the end 
of file is used. 

delete Deletes a movie or a section a movie. The from and to 

keywords can be used with delete. If no from is speci¬ 
fied, the current position is used. If the to is not speci¬ 
fied, the end of file is used. If a delete operation deletes 
the whole movie, then the error message: “The system 
has reached the end of file” will be returned to the caller. 
The file delete, however, does succeed. 

paste Copies the contents of the clipboard into the current file. 

The from and to keywords can be used with paste. If 
from and to are not specified, the contents of the clip¬ 
board are inserted at the current position. If the from 
and/or the to is specified, a delete is performed on this 
range and then the contents of the clipboard are inserted 
into the file at the from position. 

redo The redo command will cause the last edit operation to 

be re-done. The operations include: cut, paste, delete, 
and undo. The file position will be 0 after the redo oper¬ 
ation. Multiple levels of redo are supported, if the file 
format supports this. 

save The save command will save the currently edited or 

captured file permanently. After the file is saved, the 
undo command will not be able to undo the last edit 
operations. 

undo The undo command will cause the last edit operation to 

be undone. The operations include: cut, paste, delete, 
and redo. The file position will be 0 after the undo oper¬ 
ation. Multiple levels of undo are supported, if the file 
format supports this. 

The editing operations like cut, copy, and paste use the clipboard as a 
repository for the data as it is being edited from a file. Editing to and/or from 
a user-defined buffer is not supported by the digital video device. The editing 
operation can take place between two instances of the digitalvideo device or 
within one instance. There are no restrictions, however, there are come caveats 
to consider. These editing operations cannot be used to convert between data 
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types; they only work between files of the same data types. This includes both 
audio and video data type. As a rule, mixing data types within the same file is 
not possible. Once a file is saved, changes can not be undone. When saving a 
movie, the video display window will go away. It can be redisplayed by issuing 
a window state show command. Use the status position command to deter¬ 
mine the current file position after every edit operation. 

If a play command is issued after one or more editing operations has been 
performed, the playback of the video and audio may be erratic. This is caused 
by editing the video on non-I-frame boundaries. In these cases, the digi- 
talvideo device will compensate by decompressing from the I-frames and only 
showing the video frames that will exist because of the edit operation. This will 
force the digitalvideo device to potentially decompress more frames per sec¬ 
ond then the normal frame rate, which may cause synchronization problems. 
When the movie is saved, new I-frames are created at each edit point. Once the 
movie is reloaded, the playback will be smooth. 

The ability to edit movies is limited by the file format that is being used. Not 
all file formats support the editing operations. For example, the FLC/FLI ani¬ 
mation movie file format I/O procedure does not support editing animation 
files. Therefore, the editing operations will not works. To determine if the file 
format does support editing, it must support the save command. Issue the fol¬ 
lowing commands to determine this: 


“open digitalvideo alias a notify” 

“load a e:\mmos2\movies\animate.fli wait” /* loads a FLI video */ 
“capability a can save wait” /* returns FALSE */ 

“close a wait” 


When issuing edit commands like copy on a FLI video file, the operation 
may not fail, so that it would appear to work. When a paste from the clipboard 
is done into another file, the result is that whatever was in the clipboard before 
the copy command was issued will be pasted into the new file, if it is valid 
movie data. 

The following sample shows how to copy select frames from one movie and 
paste them into another movie. Both the audio and video are copied and past¬ 
ed. Note that the paste operation is always an insert paste if no from and to 
keywords are specified, meaning that a paste will insert the data from the 
clipboard at the current location. In the sample, the copy operation uses the 
from and to keywords. The from keyword indicates the starting frame and 
the to indicates the endpoint of the copy. The copywill copy up to and not 
include the actual to frame. For example, a copy from 0 to 5 will copy 
frames 0,1,2,3,4, but not frame 5 to the clipboard. 
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“open e:\mmos2\movies\macaw.avi alias source shareable notify” 
“open digitalvideo alias target shareable notify” 

“load target new notify” 


“set source time format frames wait” 
“set target time format frames wait” 
“status source length wait” 

“copy source from 0 to 5 notify” 

“paste target notify” 

“status target position wait” 

“copy source from 6 to 10 notify” 
“paste target notify” 

“status target position wait” 

“rewind target notify” 

“window target state show wait” 

“step target notify” 

“status target length wait” 

“save target e:\mmos2\movies\frames9.a 
“close source notify” 

“close target notify” 


/* 

returns 

25 

*/ 

/* 

copies 

frames 0,1,2,3,4 

*/ 

/* 

paste a 

t current location 

*/ 

/* 

returns 

0 

*/ 

/* 

copies 

frames 6,7,8,9 

*/ 

/* 

paste ( 

insert) at 0 

*/ 

/* 

returns 

4 

*/ 

/* 

show vi 

deo display window 

*/ 

/* 

display 

frame 0 

*/ 

/* 

returns 

9 

*/ 

notify” 

/* save file 

*/ 


Audio and Video Synchronization 

The digitalvideo device has the ability to keep the audio and video in sync 
during playback of a movie. Essentially, the digitalvideo device synchronizes 
the video to the audio playback. Typically, the audio playback rate can not be 
adjusted. When the video is too slow and behind in time relative to the current 
position of the audio, the digitalvideo device attempts to adjust the video 
playback so that it gets back in sync with the audio. To do this, the digi¬ 
talvideo device may either discard or decompress and not display a video 
frame in an effort to catch up with the audio position. By discarding or drop¬ 
ping a frame, the video processing takes less time and can therefore jump 
ahead in time up to one frame time relative to audio. Several frames may be 
dropped over time until the video is in sync with audio. 

In the case where the video is ahead of the audio, the digitalvideo device 
slows down the video display mechanism by lengthening the time between 
video frame displays. Therefore, the video time slows down until the audio and 
video are in sync again. 

Another reason why frames may be dropped and not displayed is if the video 
decompression for a frame takes longer than one frame interval. In this case, 
frames may be dropped completely, or just not displayed. This allows the video 
display to maintain a constant frame rate. The dropping of frames will show up 
as jerky video display and has the effect of actually lowering the effective 
frame rate achieved by the playback. For example, if a 320x240 movie is played 
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and the video display window is stretched to 640x480, the effective frame rate 
will drop. This happens because the time to decompress the video frame and to 
scale it to a bigger size will taker longer than was originally intended when the 
movie was created. So video frames are dropped in an attempt to keep the 
movie at the correct position in time relative to the original movie frame rate. 

Dropped Frame Statistics 

Sometimes it may be useful for an application to be able to query the number 
of video frames that were dropped to stay in sync with the audio or to maintain 
the frame rate. The application can query this information by using the status 
droppedframepct command. This command will return the number of 
dropped frames as a percentage of the total number of frames processed. This 
command works during play and real-time record operations. The value 
returned is in the range 0 to 100. For play, a value of 0 indicates that no frame 
drops are occurring or have occurred. A value of 100 indicates that all frames 
have been and are being dropped. For record, the returned value is the per¬ 
centage of frames that have been dropped by the capture hardware since the 
recording began. In the case of dropped frames on record, NULL frames are 
inserted in the recorded movie in place of each missing video frame. A NULL 
frame is a place holder in a movie file that represent one frame time when 
playing the movie. This allows the movie to playback at the proper frame rate. 
Otherwise, the movie would appear to play faster than normal. 

This status command returns valid information during a play or record. If 
the device is stopped, the digitalvideo device will return the value from the 
last play or record operation. A seek, pause, or stop will reset the drop frame 
percentage value for the next play operation. If no play or record operations 
have been performed, a value of 0 is returned. 

An application can use this status command to query during a real-time 
record. This status could be used in conjunction with the setpositionadvise 
command or a PM timer notification message to query the status on a regular 
interval. This information is useful, because it can give a good indication on 
what the effective frame rate achieved on a real-time record. 

Synchronization Adjustment 

The digitalvideo device provides some services for an application to dynami¬ 
cally adjust the synchronization between the audio and video streams on play¬ 
back. The Video IN product uses these services to provide the functionality for 
the user to adjust the synchronization on a newly created movie. These syn¬ 
chronization adjust services do not permanently adjust the synchronization. 
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They allow the digitalvideo device to playback a movie with adjusted syn¬ 
chronization to show what it would look like if some audio was added to or 
deleted from the beginning of the audio stream. The audiosync forward com¬ 
mand adjusts the audio time ahead relative to the video time. The audiosync 
reverse command adjusts the audio time back relative to the video time. 
These commands simulate the addition or deletion of audio at the beginning of 
the audio track. 

It is the responsibility of the application to permanently adjust the movie 
itself. This can be done by using the MMIO APIs and messages split the audio 
data from a movie, adjusting it, and then merging it back into the movie. The 
AVI file utility also provides a mechanism to split the audio from a movie into 
a separate audio file. The audio file can then be modified and then merged 
back into the movie. 


DIRECT VIDEO INTERFACE EXTENSIONS (DIVE) 


The DIVE display engine is a new component to the digitalvideo device for 
OS/2 Warp. The DIVE display engine provides an optimized blitting mecha¬ 
nism for performance critical applications that are required to perform rapid 
screen updates in the OS/2 PM and full-screen environments. Using the DIVE 
interface, applications can either write directly to video memory or use the 
DIVE blitter. The DIVE blitter will take advantage of acceleration hardware 
when present and applicable to the function being performed. It provides some 
of the following capabilities to the digitalvideo device playback architecture: 

1. It handles color space conversion for 4-, 8-, 16-, 24-bit display modes. 

2. It handles color encoding conversions between several formats. 

3. It provides pixel level clipping. 

4. It provides continuous resolution scaling, both up and down. 

5. It handles system palette changes. 

6. It provides a direct output interface. 

7. It provides backing store by default, since a decompressor must decom¬ 
press to a buffer to pass to the display engine. 

8. It eliminates the need for CODECs to handle multi-aperture 
decompression. 

The Display engine handles a lot of the things that digital video CODECs 
were required to do in previous versions of MMPM/2. This makes CODEC 
capability more consist and off-loads more work into a common component in 
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the system. This makes writing a CODEC even easier than previous versions. 
It also fixes some of the problems like: 

1. Some CODECs clipped only to a block boundary, which potentially caused 
a “gap” in the edge of the video and the window overlaying the video. This 
did not look good. This also forced the digital video window to always be 
displayed at locations on the screen that were a multiple of the block size 
defined by the CODEC. 

2. Some CODECs decompressed to one of several color encoding formats. 
This is no longer needed, because the display engine can do he color 
encoding conversion for the CODEC. This simplifies CODECs greatly. 

3. Some CODECs did not provide the ability to scale the resolution down or 
up. Other CODECs, like Ultimotion, could only scale down to 1/2 the reso¬ 
lution or up to 2 times the resolution of the original. 

4. It reduces the complexity of writing a CODEC that could handle upside 
down or right-side up display so that VGA 4-bit displays could be support¬ 
ed through the PM GpiBitBlt API. 

5. Some CODECs did not build the final images in a backing store before 
displaying the video frames. This would cause “black hole” problems when 
other windows that overlaid the video display window were moved after 
the video stopped. There was no way to repair the image on the display. 

6. CODECs are no longer required to support multi-aperture buffer decom¬ 
pression. There are a variety of ways that display hardware presents 
access to the video display buffer. Some allow the whole buffer to be 
accessed as a pointer to a memory buffer. Others present the video dis¬ 
play buffer through “apertures” of a specific size. This means that only a 
part of the video display buffer can be accessed at one time, typically in 
64KB sections. Previously, CODECs were required to support a partial 
decompression of a video frame to be able to handle the aperture switch¬ 
ing that was done by the digitalvideo device. 

DIVE APIs: 


DiveAcquireFrameBuffer Allows the frame buffer to be serialized. 

It provides a way for the caller to acquire 
exclusive access to the video frame 
memory. 

DiveAllocImageBuffer Allocates a buffer to contain an image. 

DiveBeginlmageBufferAccess Begins access to the image buffer. 
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DiveBlitlmage 

DiveCalcFrameBufferAddress 
DiveClose 

DiveDeacquireFrameBuffer 

DiveEndlmageBufferAccess 
DiveFreelmageBuffer 

DiveOpen 

DiveSetDestinationPalette 
DiveSetupBlitter 
DiveSetSourcePalette 
DiveSwitchBank 
DiveQueryCaps 

DIGITAL VIDEO CODECs 


Transfers an image from the source to 
destination. 

Calculates linear frame buffer address. 
Closes instance. 

Releases exclusive access to the frame 
buffer. 

Ends access to the image buffer. 

Deallocates an image buffer allocated by 
DiveAllocImageBuffer. 

Opens a display engine instance. 

Sets palette associated with the destina¬ 
tion of DiveBlitlmage. 

Sets up Buffer to screen or buffer to 
buffer transfer (blitter). 

Sets the palette associated with source 
data. 

Selects VRAM bank for bank-switched 
displays. 

Queries display capabilities. 


This is a list of the currently supported digital video compressors and decom¬ 
pressors available from IBM. There are also several decompressors available 
as shareware, these can typically be found on the Internet. All of these can be 
used by the digitalvideo device for playback (decompressors) or record (com¬ 
pressors). 
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Digital 

Video 

CODECs 

CODEC 

FOURCC 

SW/HW 

Decompression 

Real-time 

Compression 

Asymmetric 

Compression 

Editing 

Enabled 

Available 

From 

Ultimotion 

ULTI 

software 

yes 

yes 

yes 

Decompressor in 
MMPM/2 1.1, 
Compressors in 

Video IN. 

Indeo 2.1 

RT21 rt21 

software 

yes 

yes 

yes 

Decompressor in 
MMPM/2 1.1, 
Compressors in 

Video IN. 

Indeo 3.1 

IV31 iv31 

software 

yes 

yes 

yes 

Decompressor in 

OS/2 Warp, 
Compressors in 

OS/2 Warp Bonus 
Pack (VideoIN). 

Indeo 3.2 

IV32 iv32 

software 

no 

no 

no 

Decompressor in 

OS/2 Warp. 

FLC/FLI 

FLIC 

software 

no 

no 

no 

Decompressor in 

OS/2 Warp. 

MPEG-1 

MPEG 

hardware 
(Reel Magic) 

no 

no 

no 

Decompressor in 

OS/2 Warp. 

RAW 

DIB 

software 

yes 

yes 

yes 

Decompressor in 
MMPM/2 1.1, 
Compressors in 

Video IN. 


Table 6-1. Digital Video CODECs 

On playback of a movie, the digitalvideo device automatically determines 
the correct decompressor to use by looking at the movie file headers. When 
recording a new file, the compressor is selectable so that the application can 
choose the compression format. Currently, the default is to record movies using 
the AVI file format and the Ultimotion real-time compressor. The default can 
be changed by using the set video compression command. This command takes 
a compression FOURCC value as the compression type. For example, to record 
Indeo instead of Ultimotion, execute the following command: 
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“open digitalvideo02 alias a notify” 

“load a new notify” 

“set video compression RT21 wait” /* set compression to Indeo 2.1 */ 
“record a to 180000 notify” /* record for 60 seconds */ 


Ultimotion Compression and Decompression 

Ultimotion is IBM’s technology for software motion video. It was originally 
IBM proprietary, but the data format has been published as a tool for develop¬ 
ers to get a software-only playback algorithm at no-cost licensing. Ultimotion is 
a compression algorithm that uses no hardware acceleration for capture or 
playback. It is purely a software-only CODEC. Ultimotion does take advantage 
of the digitalvideo device display engine for hardware acceleration if avail¬ 
able on the machine. Ultimotion is also available for Microsoft’s Video for 
Windows from IBM, so it is a cross platform compression algorithm. 

Ultimotion is optimized for software-only playback and it averages 18:1 com¬ 
pression rate when using the asymmetric compressor, which compresses at 1/2 
second per frame. The real-time compressor compresses at a 4:1 compression 
rate. The quality for both can be adjusted according to desired quality (low, 
medium, high) and maximum data rate desired for playback. The real-time 
compressor can compress 15fps of live video from a capture device at 160x120 
capture size on a 33mHz 486 system. The frame possible goes down as the cap¬ 
ture size goes up. The nominal movie of 320x240 can be played back at 12- 
15fps on 25mHz 386sx at CD-ROM data rates (150kbps). The frame rate goes 
up as the data rate of the source device and the machine speed goes up. Frame 
rates of 30fps are possible on a 486 dx2 at 66mHz. 

Indeo Compression and Decompression 

Indeo is the software motion video compression technology available from 
Intel. MMPM/2 supports playback of Indeo versions 2.1, 3.1, and 3.2. The cap¬ 
ture of versions 2.1 and 3.1 are support for real-time and asymmetric. On OS/2 
2.1 (MMPM/2 1.1) versions of Indeo 2.1 did not support 16 color (4-bit) VGA 
display modes and it did not support pel-half or pel-double scaling of the video 
display resolution. OS/2 3.0 version of the digitalvideo device now supports 
continuous scaling and 16 color VGA display modes for all CODECs. Playback 
and capture of Indeo are available on several platforms. 
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FLC/FLI Animation Decompression 

FLI/FLC Animation is the industry standard animation format. It is the preva¬ 
lent format in the industry and was designed by Autodesk and is used by most 
animation tools on the market. The FLI file format, which is produced by the 
Autodesk Animator product, is most common. It is a completely lossless com¬ 
pression algorithm and is effective for synthetic images with a lot of redundan¬ 
cy in the image data. FLI is limited to 320x200 display resolution and a custom 
256 color palette. The FLC file format is an extension to FLI, which allows 
640x480 resolution. FLC/FLI video files contain only one initial I-frame or ref¬ 
erence frame, all other frames in the file are delta frames. Therefore, seeking 
within a FLC/FLI is not supported. All seek requests, seek to the beginning of 
the file. 

The FLC/FLI video files contain no audio data. The digitalvideo device, 
however, will search for an audio file (.WAV) with the same base name in the 
same directory. If it finds one, the audio will be played with the animation file 
to give the sensation of playing a movie file. Currently, the FLC/FLI script files 
that can be used for this purpose are not supported. Since the audio and video 
reside in separate files, it would not be advantageous to play these files from 
CD-ROM because of the seeking that would be necessary to read the files. 

MPEG-1 Decompression 

The MPEG-1 motion video data format, which was defined by the Motion 
Picture Experts Group, is becoming the standard motion video for TV quality 
motion video playback. It is an open industry standard and is viewed as being 
leading edge compression technology. It is a lossy algorithm and requires hard¬ 
ware assistance to playback. The actual decompression of the audio and video 
is done in hardware. The hardware also displays the video data as an overlay 
device. MMPM/2 supports the Sigma Designs Reel Magic adapter to provide 
full screen motion video at 30fps. The fact that this type of motion video 
requires hardware for playback is one of the main drawbacks to this compres¬ 
sion algorithm. The other drawback is that creating content is more expensive 
that software-only algorithms, because it also requires special hardware to 
compress the data. The MPEG video and audio data is stored in an MPEG spe¬ 
cific file format that interleaves the audio and video data. Since the MPEG file 
format does not contain an index, seeking is done to the nearest MPEG picture 
group. The size of a picture group is movie dependent, but it will typically con¬ 
tain 8 video frames. At 30fps, a seek would be accurate to within 8/30th of a 
second. The MPEG file format I/O procedure only supports playback of the 
video at normal speed or frame rate in the forward direction. MMPM/2 cur¬ 
rently supports only hardware asisted decompression of MPEG. 




Digital Video Capture 


With the ability to play digital video content, an operating system platform 
must also have the means to create digital video content. This creation of video 
content is sometimes referred to as digital video capture. Digital Video capture 
is the act of capturing video images from some type of video hardware that pro¬ 
vides the ability to “grab” frames or video images. These hardware adapters 
are called video frame grabber adapters. This chapter will briefly discuss the 
digital video device support for these type of devices with the focus on what 
services are available to an application to capture or record video content. 

On OS/2, video capture requires the use of the Video IN product. The Video 
IN product is available as part of the OS/2 WARP Bonus Pack. OS/2 WARP 
multimedia digital video support includes some of the what is needed for digi¬ 
tal video capture. The Video IN product provides the video compression 
CODECs, the video capture device drivers, the Software Video Recorder 
Application, and the AVI file utility program. 

The Software Video Recorder is an application that can record or capture 
movies and images. It can record either from hardware or from another file. 
The application also provides an editing facility that can be used to edit 
movies. The record from file and edit functions do not require any video cap¬ 
ture hardware. The AVI file utility program is a tool to browse and manipulate 
AVI files. It has the ability to split audio and video data from a movie file into 
separate files and to merge them back. It also can be used to create a movie 
from a series of bitmap images. 
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DESCRIPTION OF VIDEO CAPTURE ARCHITECTURE 


The act of capturing video can be done in two ways: real-time or non-real-time. 
Real-time recording is a method of capturing live video directly from a frame 
grabber adapter in real-time. This means that video is captured at a specific 
frame rate with the intent that it can be compressed quickly enough to sustain 
the chosen frame rate. This is sometimes referred to as symmetrical compres¬ 
sion or capture because the capture and compression of each frame takes about 
an equivalent amount of time as it takes to decompress the same video frame. 
The focus of this type of capture is not to capture and compress for the best 
playback quality, but to record the essential elements of a live video source. 

Non-real-time capture is sometimes called frame-step, off-line, or asymmet¬ 
rical capture. Frame-step recording is a method of capturing and compressing 
video data using a slower mechanism. The capture and compression of video is 
done one frame at a time, with the goal, not being sustained frame rate, but 
high quality compression. Typically, this type of compression takes much 
longer then the corresponding decompression of the same video frame, hence, 
the name asymmetric. The term off-line is used because, normally, a live video 
feed is not used for this type of video capture. A frame steppable device like a 
Laserdisc would normally be used for this type of capture. This type of capture 
could also be used to record from an existing file. 

MMPM/2 supports both types of capture, but in much different ways. 
Currently, only software-only compression algorithms are supported under 
MMPM/2. For real-time recording, the digital video device provides services to 
capture audio and video in real-time. An application can use the digitalvideo 
device record command to request this type of capture. Frame-step capture on 
the other hand, is a much more complicated process. An application must do a 
large majority of the work. Some basic services are provided by MMPM/2 to 
help an application. The digitalvideo device provides services to capture an 
image from a video frame-grabber hardware. The Software Video Recorder, as 
an example application, uses this service to retrieve images. An application 
must also control the video feed device directly, for example, a laserdisc can be 
controlled through the MCI interface laserdisc device. In addition to the device 
control, an application must also handle the compression and file management 
directly, the digitalvideo device does not provide these types of services. 
Although, the MMIO subsystem can be used to provide file management and 
data compression services. The MMIO subsystem, with its pluggable file for¬ 
mat and CODEC procedures, provides the necesssary file format inependent 
interfaces required for a general purpose digital video recorder. The Off-Line 
Video Capture section of this chapter will provide more details on services 
available for an application to perform off-line recording. 



Real-Time Video Recording 
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Real-time video capture uses a live video source and it is good for things like 
video conferencing type applications or applications that are required to dis¬ 
play the results of the video capture immediately. This is a one step process, 
where the interleaving of audio and video is done as the data is captured and 
compressed in real-time. This type of capture is also called symmetrical cap¬ 
ture, because the compress time is roughly the same as the playback time. The 
frame rate determines the amount of time available to compress each video 
frame. 

In most cases, as the capture frame rate increases, the loss of video frames 
can occur because the amount of time available to compress is less and the sys¬ 
tem tends to backs up. The lost frames are called NULL frames. These NULL 
frames are stored in the resultant file, so that when the movie is played back, 
it plays at the correct rate. These NULL frames basically have the effect of 
just reducing the actual frame rate of the movie. So when capturing real-time, 
the frame rate should be tuned to eliminate NULL frames if possible. 


Real-Time Digital Video Record Architecture 



Figure 7-1. Real-time Digital Video Record Architecture 
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To perform a real-time record, the digitalvideo device uses the MMIO sub¬ 
system and the streaming subsystem similar to the playback of digital video. 
The components of the system are connected in a different manner. Figure 1. 
Real-time Digital Video Record Architecture shows the interconnection between 
the components of the digital video device. Some of the same components are 
shared with the audio subsystem and the digital video playback system. It also 
shows the data flowing from the audio and video capture devices ultimately to 
a movie file in the bottom middle of the figure. 

Opening the Digital Video Capture Device 

An application must first open the digitalvideo device before it can be used. 
To capture video, a digitalvideo device must be attached to video capture hard¬ 
ware. Not all digitalvideo devices can perform recording functions. Usually the 
second digitalvideo device, or digitalvideo02 will record. This chapter will 
use the name digitalvideo02 to mean any digitalvideo device that can 
record. The digitalvideo02 capture devices will have different sharing charac¬ 
teristics from the digitalvideo playback device. It depends on the hardware 
implementation. Most capture hardware should support multiple open 
instances, with only one of them being active at a time. This is called serially 
shareable. Only one instance of the digitalvideo02 capture device will be able 
to control the hardware at a time. This will apply to video overlay cards as 
well. 

Loading a Output File For Captured Data 

Before a record can take place, there needs to be a file created or opened to 
store the capture output. An application can either specify a file to record to, or 
specify that a new file should be created. This file will be created with some 
default values for recording attributes like, frame rate, image size, and quality. 
The digitalvideo02 device internally issues MMIO API calls to open or possi¬ 
bly create a file and then writes file headers to the new file, using the defaults. 
The headers are created and set using the standard presentation header for¬ 
mat for a movie file. These headers are specific to movie files, but are file for¬ 
mat independent. A load new command will instruct the digitalvideo02 
device to create a new file for the capture output. If a load new command is 
issued by the applicaion, the digitalvideo02 device will record to a tempo¬ 
rary file. The results of the record can be saved permanently by using the 
save command with a file name. An application can also record over an exist¬ 
ing file by using the load or open command with an existing file name. A tem¬ 
porary file is used in this case as well, so that the record can be “undone” by 



Digital Video Capture 275 


not saving the file. A record to an existing file will always replace the file. 
There is no ways to indicate that save should insert into an existing file. The 
editing commands can be used to do this type of operation. 

Setting Digital Video Device Capture Attributes 

The default settings for real-time recording are 160 by 120 resolution, 15 
frames per second, and Ultimotion compression type. The application can over¬ 
ride any defaults by using the digitalvideo02 set command to set a new out¬ 
put frame rate for instance. There are several attributes that control the quali¬ 
ty of the capture as well as the rate. It is also possible to select the type of 
audio to record as well. The default is 8-bit, mono, 22500 samples per second 
audio. Not all types of audio can be used to record. Two forms of compressed 
audio are supported on record. Using a compressed audio format can greatly 
reduce the size of the captured movie file. The drawback for this method, is 
that the audio data must be decompressed at playback time. This process will 
require slightly more processing power to playback a movie. 

A developer should experiment with these setting to tune the record for the 
desired results. Refer to the Setting Device Controls and Attibutes section of 
the Digital Video Device Fundamentals chapter for the list of possible attribut¬ 
es that can be changed. The application should acquire the digitalvideo02 
device exclusively while setting record attributes and during record. This is 
necessary when multiple applications are trying to use the resource at the 
same time. By acquiring the digitalvideo02 device exclusively, it will acquire 
the ampmix device exclusively. This will prevent another application from 
acquiring the device while a record is taking place. The application can then 
release the device when the record is complete. 

One of the attributes that can be set is the type of compression algorithm 
(CODEC) that should be used to compress the captured video data. Optionally, 
it is possible to capture RAW, which means the video data is not compressed. 
The default CODEC that will be used is the Ultimotion real-time compressor. 
The digitalvideo02 device will load the default CODEC if the application does 
not request a specific CODEC be used during the capture of video data. The fol¬ 
lowing sample shows how to select another compression CODEC for real-time 
capture. 


“open digitalvideo02 alias a notify” 

“load a new notify” 

“set video compression IV31 wait” /* set compression to Indeo 3.1 */ 
“record a to 360000 notify” /* record for 2 minutes */ 
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Once an application selects a CODEC, the digitalvideo02 device will asso¬ 
ciate the CODEC with the output file. The digitalvideo02 associates a 
CODEC with a file by using the mmioSet API to direct the movie I/O proce¬ 
dure for the output file to load and open the CODEC. The movie I/O procedure 
will also update any compression specific information saved in the file headers. 
The association process also initializes the compressor based on any set com¬ 
mands that alter the behavior of the CODEC. For example, the set video 
quality command can be used to modify the quality of the compression 
process. 

The put record source at command is used to specify the video capture 
region that should be captured from the video source. Typically, this is set to 
the maximum size of 640 by 480. The capture position is also specified on this 
command. It typically is set to a cordinate position of (X=0,Y=0). The put 
record destination at command is used to specify the desired output video 
size. The default is 160 by 120. This can range up to a maximum of the cap¬ 
tured region. By changing the output size of the video, the desired frame rate 
may not be achieved during the capture. As a rule, the larger the output size, 
the lower the frame rate that is possible. 

An application can specify that only video data is to be captured during a 
record operation. The following string interface commands can be used to 
record a video only file. 


“open digitalvideo02 alias a notify” 

“load a new notify” 

“set a record audio off wait” 

“record a to 180000 notify” /* record for 1 minute */ 

“save a vid_only.avi notify” 

“close a notify” 


Monitoring a Capture 

It is possible to monitor a movie capture, both visually and audibly. The audio 
can be monitored by directing the connected ampmix device to enable the 
monitor connector. The video can be monitored by using the set monitor on 
command to indicate that during the record operation, the video should be dis¬ 
played as it is captured. It is not necesssary to do a record to monitor a live 
video source. 

This monitoring can be done either in software or in hardware. If the video 
capture hardware is an video overlay device, the hardware can display video 
directly on the screen during capture. This process would have no impact on 
the processing power during capture. Some video capture hardware also will 
allow an external display to be attached directly to the hardware. This allows 
the video to be displayed on this external monitor. 
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In the case that no video overlay capability exists, the digitalvideo02 
device will use a software monitor. This means that as the video is captured 
into the system, some of the video frames are displayed on the screen. The 
monitor will attempt to display a video frames at a rate of 2 frames a second. 
The amount of video frames that are display is strictly a function of the 
amount of processing power available during the record operation. If monitor¬ 
ing without record, the monitor will attempt to display the video at the default 
frame rate of 15 frames per second. Monitoring in software will affect the maxi¬ 
mum frame rate possible. Therefore, to achieve the maximum frame rate, do 
not use the software monitor during capture. 

The monitor video output is displayed in the default video display window. 
The window and put commands can be used to indicate position and size of 
the window. They can also be used to display or hide the window. The window 
command will also allow the monitor output to be directed to an application 
specified window. 

In the following string interface sample, the monitor is turning on, so that 
the incoming video signal can be viewed in the default video window as it is 
recorded. 


“open digitalvideo02 alias a notify” 

“set a time format frames wait” 

“set a monitor on wait” 

“cue a input notify” 

“record a to 900 notify” /* record 1 minute of video */ 

“close a notify” 


Cue The Digital Video Device For Input 

After the digitalvideo02 device record attributes are set, the application will 
typically issue a cue input command to indicate to the digitalvideo02 device 
that it should create the capture data streams to be used for capture. A data 
stream cnsists of a queue of buffers. These buffers. These buffers are allocated 
and managed by the stream manager. 

The cue input command is an optional operation. It is not required to 
record, but the cue command will guarantee that the device is initialized and 
ready to record. This provides the quickest response to the start of a record. 
When capturing a live video source, it is important for the record command to 
start the actual capture process immediately when requested to do so. This will 
prevent the possibility of losing some of the initial video and audio data. If a 
cue is not issued, the record command will cause the data streams to be cre¬ 
ated and set up the device before the actual capture process will begin. 
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The digitalvideo02 device, on a cue input, will create the data streams. If 
the application or user requested that audio is to be captured, then an audio 
stream is set up from the audio capture device to the multi-track stream han¬ 
dler. For video, a stream is set up from the video capture device to the com¬ 
pression stream handler. This stream will queue video frames from the capture 
device to the compressor. The compressor is called by the compression stream 
handler through the CODEC access messages provided by the movie I/O proce¬ 
dure. The final stream is setup from the compression stream handler to the 
multi-track stream handler. As the compression stream handler dequeues cap¬ 
tured video frames, it calls the compressor to compress it. After it is com¬ 
pressed, the compression stream handler will queue the compressed frame on 
the stream that goes to the multi-track stream handler. 

The multi-track stream handler receives audio and video data from their 
respective queues and passes these buffers of data to the movie I/O procedure. 
It uses the MMIOM_MULTITRACKWRITE message to “write” the data to a 
file. The movie I/O procedure has the job of trying to interleave the data and 
also, not cause the system to backup. For real-time record, the interleave ratio 
is roughly about 5-to-l or five video frames for every audio chunk of data. It is 
not efficient to attempt to interleave the audio and video, 1-to-l on a real-time 
record. The file can be re-interleaved by using the AVI file utility program if 
this is desired. 
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Figure 7-2. Real-Time Digital Video Record Data Flow 
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When a video monitor is turned on and the monitoring is done in software, 
the digitalvideo02 device will also create a data stream from the video cap¬ 
ture device to the video stream handler. One of the advantages of using the 
streaming subsystem to queue buffers of data is that a buffer can be passed in 
multiple queues. The video capture stream handler uses this concept to pass 
the captured video data buffers to both the compression stream handler and 
the video stream handler. The video stream handler will display the data on 
the screen, while the compression stream handler compresses the data. The 
data is not copied to each stream handler, buffer pointers are all that is passed 
in the stream queues. If an application intends to display a monitor during 
record, it should set the monitor on before issuing a cue or record 
command. 

Using this system, all real-time captures are done at a constant frame rate 
and frame size. The frame rate and frame size cannot be dynamically altered 
once the cue input or record has been issued. If the frame rate or frame size 
is changed, the streams are destroyed and recreated with the new information. 
So, this is another caveat. An application should set all record attributes 
before issuing a cue input is issued. They should not be changed after the cue 
input. Each time a load command is issued, the record attributes will be 
reset. 

The hardware video quality attributes such as brightness, contrast, and 
sharpness can be altered during a record operation. The list of device setting 
keywords in the Digital Video Device Fundamentals chapter indicate which 
record attributes can be set or changed during a real-time record. 

Capturing and Saving the Data 

The record operation can be started by issuing a record command to the digi- 
talvideo02 device. The to keyword can be used to indicate an ending point for 
the capture. If the to keyword is not used, the stop command can be used to 

stop the record. 

After the recording operation is complete, the the movie can be played back 
by using the play command. Use the save command to save the captured data 
into a permanent file. To save the movie data as a video file, an application can 
specify an existing file name or a new file name. If the application indicates an 
existing file name, the data in the file will be completely replaced by the data 
in the temporary file. 

Off-Line Video Capture 

The following steps can be used to do an off-line capture of video. A frame-step- 
pable device can be used or another movie file can be used as input. These step 



280 


Developing Multimedia Applications Under OS/2 


show how to record from a device. These steps will create a 1-to-l audio and 
video interleaved movie file. 

1. Open laserdisc device and seek to the correct position. Connect the audio 
output to the audio card input. Connect the video output to the video cap¬ 
ture card input. 

2. Pre-record the audio portion to a file using the waveaudio device. 

3. Seek the laserdisc device to the correct position. 

4. Open the input audio file using the mmioOpen API. 

5. Read the audio file headers by using the mmioQueryHeaderLength and 
mmioGetHeader APIs. 

6. Open the output movie file using mmioOpen API. 

7. Create standard presentation headers for the output file. Use the 
mmioSet API and the mmioSetHeader API to write the new headers to 
the output file. The mmioSet API will set the current track. 

8. Associate a compression CODEC using mmioSET API. 

9. Loop for the length of the video to record. 

10. Read a buffer of audio data from the audio file using the mmioRead API. 
The amount should be equivalent in time to the frame duration. 

11. Capture a video frame from the capture device using the procedural 

MCI.GETIMAGEBUFFER message. 

12. Use the CODEC Access message, MMIOM_COMPRESS, to compress a 
video frame. 

13. Use the MMIOMJV1ULTITRACKWRITE message to write the video 
frame to the video track of the output file. 

14. Use the MMIOM_MULTITRACKWRITE message to write the audio 
data to the audio track of the output file. 

15. Step the laserdisc device by one frame. 

16. Go to step 9. 
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Figure 7-3. Frame-step Digital Video Record Data Flow 


HARDWARE REQUIREMENTS 


To do digital video capture, it is recommended that a 486 or Pentium processor 
be used in a machine that has a least 12MB of memory. This machine should 
have a big hard drive. It needs to be large enough to store the movie data. 
Room will also be needed to edit the files as well. A video capture device to cap¬ 
ture the video data is required to capture data fron a laserdisc, VCR, or some 
other video source. For asymmetric capture, a frame-steppable laserdisc is rec¬ 
ommended. A frame step VCR can be used, but the device must be manually 
stepped by the user. MMPM/2 does not provide software to control a VCR. An 
audio capture device is also required if audio capture is desired. 

External monitor is recommend, if capture hardware can connect to it. This 
provides way to monitor without using additional processing power to do the 
monitoring on the computer. Software monitoring lowers the maximum effec¬ 
tive frame rate for a real-time capture. Dropped frames may appear more 

















282 Developing Multimedia Applications Under OS/2 


fequently. For a list of video capture and laserdisc devices supported by the 
Video IN product, refer to the MMPM/2 Device and Software Support chapter. 

For RAW captures, the more memory, the better perfromance up to a point. 
This is because RAW video frames can be very large. Even if the frames are 
compressed, they are captured from the video card as RAW data, therefore, the 
bigger the frame size, the bigger the buffers need to be, hence, more memory. 
For example, 640 by 480 at 16-bits per pixel is 614400 bytes per video frame. 


COMPRESSION CODECs 


There are several compressors that can be used to record a movie. There is a 
table in the Digital Video Device Fundamentals chapter that lists the support¬ 
ed CODECs available. Also refer to the Using Multimedia I/O (MMIO) chapter 
for details on the CODEC interfaces and using a CODEC. 

Some compression types supply a real-time and an asymmetric compressor 
and some do not. The real-time compressor for any CODEC can not only be 
used for real-time recording, but also for off-line recording. The drawback, is 
that the quality will probably be much better with an asymmetric compressor 
than a symmetric compressor. It is not recommended that any of the asymmet¬ 
ric compressors be used for real-time recording. This would severely restrict 
the possbile frame rate that could be achieved. 

Video under MMPM/2 can also be captured as RAW video data and stored in 
a file as RAW data. RAW is uncompressed video. Capturing RAW data will use 
much more hard drive space then compressed captures. Of course, if disk space 
is not a problem, there would be no need to compress the data. But, disk space 
is still expensive and as disk space grows, applications seem to take advantage 
of the new space—causing the user to always be in a state of needing more disk 
space. Look at the disk compression algorithms that are taking root as regular¬ 
ly available on every machine to double your disk space. They are transparent 
to applications. 

It can be useful in that a real-time capture can create a RAW movie that can 
later be compressed off-line using a better quality aymmetric compressor. A 
from-file capture can be used to capture, off-line, data from a file. For example, 
the frame step Indeo compressor could be used to compression the video data, 
off-line, from a RAW movie captured real-time. In this case, a frame-step 
laserdisc is not required and the quality of the capture will be better. This is 
especially useful when no real-time compressor exits for the video format 
desired. The drawback is that RAW can take large amount of disk space, that 
is why you compress it. 
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RAW movies also come in handy when providing movie content is several 
video formats. The quality will be better if each video file of a format is created 
from the RAW data instead of trying to convert a previously compressed movie. 
The decompression process will lose some of the quality and hence the corre¬ 
sponding compression in another format will not be as good. 


CAPTURING IMAGES 

MCI_GETIMAGEBUFFER with the MCI_USE_HW_BUFFER flag is sup¬ 
ported today on the digital video record device attached to the appropriate 
hardware device. An application passes a buffer to the device, which fills the 
buffer with an image (OS/2 bitmap—.BMP form) and returns to the applica¬ 
tion. The application must then save the image to any file it wants to, or in the 
case of off-line (frame-step) recording, it can call a video compressor to com¬ 
press the video information before writing it to a file. 

The digital video device does not currently support the following image 
related commands: 

• MCI.CAPTURE 

• MCI.GETIMAGEBUFFER without the MCI_USE_HW_BUFFER 

• MCI.SAVE with the MCI_DGV_SAVE_IMAGE_FILE flag 

Other digital video devices, like the DVI digital video device may support 
these commands. To determine whether a device supports image-related com¬ 
mands, use the CAPABILITY command to query if the device HAS IMAGE 
support. 


open digital video alias a wait 
capability a has image wait 


TV TUNING SUPPORT FOR VIDEO OVERLAY DEVICES (WIN/TV) 


Some hardware overlay devices have tv tuner built in. The digitalvideo02 
device can take advantage of this hardware functionality. The set monitor on 
command can be used to display the TV signal. The WinTV adapter is an over¬ 
lay card that can capture video and receive a television signal. To capture the 
TV signal from the hardware device, the tuner must be selected as the input 
connector. For a WinTV adapter, there are two connectors: live video input and 



284 Developing Multimedia Applications Under OS/2 


the TV tuner signal. The default for the digitalvideo02 device is to capture 
video from the live video input connector. The actual default and number of 
connectors depends on the hardware attached to the digitalvideo02 device. To 
select the tv tuner as the input, use the following string interface sample. The 
sample selects channel 3 from the geographic region of the United States. An 
application can issue a settuner command to set attributes of the TV tuner. 
These attributes include region, channel, and finetune value. The procedur¬ 
al MCI_ESCAPE command can be used to set the volume for the tv tuner. 


“open digitalvideo02 alias a notify” 

“capability a has tuner wait” /* returns TRUE if has tv tuner */ 

“connector digitalvideo02 enable type video in number 2 wait” 

“settuner a tv channel 3 region usa finetune plus 1 wait” 

“set monitor on wait” 

“window a monitor state show” 


VIDEO CAPTURE DEVICE IOCTL FUNCTIONS AND VSD INTERFACES 


The video IOCTL interface is a generic video capture device driver interface. It 
is primarily used to set video attributes such as brightness, hue, and satura¬ 
tion. This interface is also used for video device setup of various capabilities 
that a typical video capture device or video overlay device is capable of. 
MMPM/2 uses these interfaces indirectly through a device independent layer 
called the VSD or Vendor Specific Device Interface, therefore, an application 
should never uses these interfaces directly. 
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Category 140h lOCTLs: 


Function Number 

Description 

60h 

Setup information from INI file 

61h 

Save device state 

62h 

Restore device state 

6Ah 

Set/query video input source connector 

6Bh 

Set source and streaming capture information 

6Ch 

Get image and scale into RAM buffer 

6Dh 

Get device information 

6Eh 

Validate video rectangle 

72h 

Unfreeze the image digitizer 

74h 

Freeze the image digitizer 

75h 

Set/query video adjustments 

76h 

Set frame rate for streaming 

80h 

Enable or disable overlay monitor (overlay devices 
only) 

81h 

Enable/disable color keying (overlay devices only) 

82h 

Set transparent color (overlay devices only) 


Table 7-1. Video Device IOCTL Table 

The VSD interface is a device independent interface that is provided as an 
OS/2 Dynamic Link Library (DLL). MMPM/2 provides a standard VSD for 
video and these can be used by all device drivers that conform to the video 
IOCTL interfaces mentioned above. Vendors can provide their own VSD that 
maps to their hardware, as long as, the VSD conforms to the standard VSD 
definition as defined by IBM for MMPM/2. MMPM/2 uses the VSD interface for 
all device communications. There should be no need for an application to use 
the VSD interfaces directly, hence we will not discuss the details of this or the 
IOCTL interface. 
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INTRODUCTION 


Compact Disc or CD players have been available for the consumer market for a 
number of years. These CD players come as basic as Walkmans to multidisc 
carsouls. The personal computer market began a few years ago provided CD 
Read Only Memory or CD-ROM drives as a secondary storage media. These 
discs can hold 600+ megabytes of data. The CD drive manufacturers then 
began to provide CD digital audio functionally on the same drive. This meant 
that these drives could playback the digital audio data found on normal music 
CDs. These CD as referred to as CD DA discs. MMPM/2 has supported CD/DA 
drives since release 1.0. OS/2 supports a large number of these CD drives. 
MMPM/2 also supports this set of CD/DA drives. MMPM/2 provides control of 
these devices much the way a remote control would. For a list of the MMPM/2 
supported CD-ROM drives see the table on CD devices in the MMPM/2 Device 
and Software Support chapter. 

CD/DA Data 

Standard CD-ROM discs contain data that can be accessed by the operating 
system’s file system. This data is presented to applications in the same manner 
as data on the hard disk or diskettes. This access to the CD-ROM data is 
through the normal file system APIs, such as DosOpen, DosClose , DosRead 
and DosWrite. The CD-ROM access is provided by the CD-ROM installable file 
system. Because CD-ROM discs are read-only, these discs are used to contain 
large amounts of data that is accessed directly or copied to the hard disk. The 
majority of the data on these accessed from applications, such as multimedia 
applications. 
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The CD-ROM drives also allow for the access of CD Digital Audio or CD/DA 
discs. These digital audio CDs are the same CDs one would buy in a record or 
music store. The encoding standard is for CD/DA disc is call “Red Book.” The 
“Red Book” standard refers to the layout and access of digital audio data on a 
CD. 

The digital audio data contained on a CD/DA disc is very high quality audio. 
It is 16-bit, 44 kHhz stereo PCM audio. This digital audio can not be accessed 
using the normal file system APIs. OS/2 provides a extended set of APIs as 
part of the CD file system. These interfaces allow for the reading of “long” 
records from the CD. These capability is not available on every CD-ROM drive. 
The CD-ROM device drivers also allow for the playback of the digital audio 
data through the built-in hardware. 

Streaming vs. DAC 

The digital audio data can be played back one of two ways. The first way is 
through the digital to analog converter or DAC that is built into the CD-ROM 
drive. This DAC takes the digital PCM audio data and converts it into its ana¬ 
log equivalent. The analog audio output is then outputted through a head¬ 
phone jack, usually on the front of the drive. In addition, some CD-ROM drives 
have line out jacks on the back of the drive, which may be connected directly to 
speakers or to the line in jack of an audio card. The volume control for this 
audio playback is usually a volume knob on the front of the drive. The play¬ 
back of the audio from the CD using the DAC does not involve transferring the 
data to the system. All of the data is transferred internally on the CD-ROM 
hardware. This mode of playback incurs very little system overhead. MMPM/2 
refers to this mode of playback as internal process or non-streaming. 


CD MCD 


1 1 


CD VSD 


IOCTL j 

\ 

CD-ROM 


Device Driver 





Speaker 


Figure 8-1. CD DAC Playback 
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The second playback mode of the CD-ROM drive is called “streaming.” 
Streaming the digital audio data involves reading the digital audio data from 
the CD-ROM drive and sending or streaming it to an audio card using the 
streaming sub-system of MMPM/2. This mode of playback is identical to nor¬ 
mal audio playback from a waveform file. The only difference is that the data 
comes from a different media. The movement of the data is through the 
MMPM/2 streaming subsystem. The CD-ROM drive behaves like a hard disk 
providing data to device driver read requests. The CD audio stream handler 
makes read requests to the CD-ROM device driver for the digital audio data. 
The read requests are interpreted by the device driver and the requested data 
is transferred to the stream handler’s buffer. Not every CD-ROM drive sup¬ 
ports this mode of digital audio playback. The chapter on MMPM/2 Devices 
provides a list of CD-ROMs drives supported by MMPM/2. This lists the CD- 
ROM drives that support digital audio streaming. 


CD Audio 
MCD 



Figure 8-2. DAC vs. Streaming CD Audio 

To determine the playback capabilities of the CD device issue the following 
two capability commands: 
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“capability cdl can process internal wait 
“capability cdl can stream wait” 


These MCI commands determine if the device can playback using an inter¬ 
nal DAC and/or stream the digital audio data. 

Once an application has determined that a CD-ROM device can stream its 
digital audio data, the connector command can be used to enable this stream¬ 
ing mode. The command: 


“connector cdl enable type cd stream wait” 


enables the CD device instance for streaming mode vs. DAC playback. This 
commands switches from DAC playback mode to streaming mode. The current 
CD-ROM drives can not playback the digital audio in both mode concurrently. 
To switch back to DAC playback mode issue the following command: 


“connector cdl disable type cd stream wait 


When the connector command is issued to enable CD audio streaming the 
CD MCD does the following: 

1. Opens instance of AmpMix device 

2. Connects the CD stream Connector to the AmpMix stream connector 

3. Sets up the stream between the CD stream handler and the audio stream 
handler 

Just like the waveaudio setup, the ampmixer device instance connected to 
the CD audio device instance can be accessed directly. To access the ampmix 
device instance either the ampmix device instance ID must be obtained or an 
alias for the ampmix device instance must be created. The connection com¬ 
mand can be used to create an alias for the ampmix device instance. 


connection cdl query type CD Stream alias ampl wait” 


This command queries the ID of the device instance connected to the CD 
stream connector of the CD device instance and assigns the alias ampl to it. 
Audio commands such as volume, bass treble, etc. can now be sent to the alias 
ampl. This is the preferred method of dealing with ampmix device instances 
connected to other device instances. 
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As mentioned before the digital audio data that is streamed is 16-bit 44kHz 
stereo. This high quality digital audio data requires 172k bytes per second of 
data. This load on the system should be avoided if DAC playback will suffice. 
Applications using the CD-ROM device should determine the requirements 
before using the streaming mode. If playback using the headphone jack or the 
line out jack on the CD-ROM will meet the applications requirements, then 
streaming the data is not necessary. If the application requires the data to be 
played out an audio card then streaming is required. 

MMPMCD.INI File 

Because of the varying degrees of functionality of CD-ROM drives MMPM/2 
maintains a INI file describing the characteristics of each drive. This file 
includes all of the drives supported by OS/2. This INI file is created from a 
resource file that IBM updates as new CD-ROM are supported by OS/2. The 
format of the resource file is the following. 


FIELD 

Data Type 

Vendor ID 

8 CHARs 

Product ID 

16 CHARs 

Entry Version 

USHORT 

Capability Flag I 

ULONG 

Capability Flag II 

ULONG 

VSD DLL name 

8 CHARs 

Min. Starting Address 

ULONG 

Volume Level Counter 

USHORT 

Volume Control Commands 

101 USHORT 


Table 8-1 . CD Resource File Layout 


Each drive that is supported has a record, as above, that describes its capa¬ 
bilities. This makes adding new CD-ROM drives to MMPM/2 a data driven 
process vs. updating the code. The Capability flags of this record are described 
in Table 8-2. 
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Value 

Description 

0x00000001 

Can Software eject disc 

0x00000002 

Can lock drive/disable eject 

0x00000004 

Can read raw sectors 

0x00000008 

Can write to disc 

0x00000010 

Can play CD-DA tracks 

0x00000020 

Supports ISO-9660 interleaving 

0x00000080 

Can prefetch internally 

0x00000100 

Can manipulate audio channels 

0x00000200 

Can us Redbook mode 

0x00000400 

Can read CD-ROM/XA data 

0x00000800 

Continues to read DA after stop 

0x00001000 

Can play in reverse 

0x40000000 

Can read CD-DA audio tracks 


Table 8-2. Capability Flag I 


Value 

Description 

0x00000007 

Volume dependency mask 

0x00000000 

Volume without dependency 

0x00000002 

Volume is highest value 

0x00000003 

Volume is lowest value 

0x00000004 

Volume is left volume 

0x00000005 

Volume is right volume 

0x00000008 

Mute has no dependency 

0x00000010 

Can only lock when mounted 

0x00000020 

Can play video 


Table 8-3. Capability Flag II 
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Value 

Description 

0x00000040 

Stop req. to interrupt PLAY 

0x00000080 

Supports SEEK IOCtl 

0x00000100 

Supports UPC IOCtl 

0x00000200 

Supports sub-channel IOCtl 

0x00000400 

Can close door/retract caddy 

0x80000000 

Supports variable speeds 


Table 8-3. Capability Flag II (Continued) 

This information can be retrieved using the PM profile APIs. The 
Application name is the Vendor ID and the Key name is the Product ID. This 
information is retrieved and used by the CD audio VSD. The format of the data 
returned is as follows. See the CDAUDOS2.H header file for more details. 


typedef struct _MMPMCD_REC { 

USHORT usEntryVer; 

ULONG ulCapsl; 

ULONG ulCaps2; 

CHAR VSDName[CDINI_VSD_NAME_SIZE]; 

ULONG ulMinStart; 

USHORT usVolCnt; 

USHORT ausVolValues[V0LUME_C0NTR0L]; 

} MMPMCD_REC; 


Volume 


During DAC playback mode, CD-ROM drives have unique volume settings. 
The number of volume levels or steps supported depends on the CD-ROM 
drive. The range is from two levels to 101 levels. The CD-ROM drive list in the 
External device chapter lists the volume levels for each drive. Volume com¬ 
mands are set in as a percentage of 100. If the CD-ROM device supports some 
number of volume levels less than 100 than it adjusts the volume based on var¬ 
ious ranges. For example: a CD-ROM that supports three levels (0, 50, 100) 
might have volume settings 0-33 as level 1, 34-66 as level 2 and 66-100 as level 
3. To determine if the CD-ROM device’s volume can be change through 
MMPM/2 use the capability command with the can setvolume keywords. 
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“capability cdl can setvolume wait” 


This command tells whether the drive’s volume can be changed via software. 
It does not give any information about the number of volume levels. Currently 
there is no MMPM/2 command to determine the number of volume levels. The 
query of information from the MMPMCD.INI file would give that information. 

Volume for CD audio devices, like other devices, can be changed over a spec¬ 
ified time period. This provides the effect of either a fade in or fade out. The 
keyword for this vectored change in volume is over. The vectored delay time is 
expressed in milliseconds. 


“set cdl audio on volume 50 over 2000 notify” 


This sample changes the current volume setting to 50% over 2 seconds. 
Notice that the notify keyword is used. This is because the command is going 
to take 2 seconds to complete and applications should not tie up a thread for 
that amount of time. Unlike audio devices that support the full range of vol¬ 
ume levels (0-100), some CD audio devices may step level effect for vectored 
volume. 

Cuepoints and Setpositionadvise 

CD audio devices support cuepoints and positionadvise messages just like 
the other MMPM/2 devices, except for the accuracy of these messages. CD- 
ROM drives do not report status via interrupts like audio cards. They must be 
asked or polled for their status. This means that the CD audio MCD must poll 
the CD device periodically to determine its playback position and device status. 
The frequency of polling versus the accuracy is a tradeoff that the CD audio 
MCD makes. 

The CD audio MCD polls the CD-ROM device using the following algorithm. 
It starts polling at a low frequency about once per second. It maintains some 
number trigger events. Trigger events are cuepoints, positionadvise, seek to or 
play to events. These trigger events have a time associated with them. When 
the trigger event time is reached the trigger event occurs. As the trigger time 
of events gets closer the CD MCD begins to poll at a higher rate. The frequency 
will begin to get closer to 250 milliseconds per poll until the trigger event time 
is encountered. If no trigger events are queued up, then the polling remains at 
the lowest frequency. This polling (no trigger event polling) is required to check 
the status of the drive. This status may change at any time for things like the 
disc being ejected. 
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Table of Contents 

The CD audio device supports the MCI_GETTOC command. This command 
returns a table of contents for the currently loaded disc. Since this command 
returns information in a defined structure it is not available from the string 
interface. The following structures define the table of contents that is returned. 


typedef struct _MCI_TOC_PARMS { 
HWND hwndCal1 back; 

PTOCREC pBuf; 

ULONG ulBufSize; 

} MCI_TOC_PARMS 


typedef struct _MCI_TOC_REC { 
BYTE TrackNum; 

ULONG ulStartAddr; 

ULONG ulEndAddr; 

BYTE Control ; 

USHORT usCountry; 

ULONG ulOwner; 

ULONG ulSerialNum; 

} MCI_TOC_REC; 


This call will return a number of records, one for each track. Since the appli¬ 
cation must allocate the number of MCI_TOC_REC structures to be passed in 
it must know the number of tracks for the currently load disc. The status com¬ 
mand should be used to query the number of tracks for the currently loaded 
disc. The following example shows how to query the number of tracks and then 
to issue the MCI_GETTOC command. 


pStatus.hwndCal1 back = hwnd; 

pStatus.ulItem = MCI_STATUS_NUMBER_OF_TRACKS; 

mciSendCommand (usDevicelD, 

MCI_STATUS, 

MCI_WAIT | MCI_STATUS_ITEM, 

(PVOID)&pStatus 
0 ); 

ulNumTracks = pStatus.ulReturn; 

(PVOID)pTocRecs = mal1oc(sizeof(struct MCI_T0C_PARMS) * ulNumTracks); 
TocParms.pBuf = pTocRecs; 

TocParms.ulBufSize = sizeof(struct MCI_T0C_PARMS) * ulNumTracks; 
mciSendCommand (usDevicelD, 
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MCI_GETTOC, 

MCI_WAIT, 

(PVOID)&TocParms, 

0 ); 

By querying the number of tracks for the current disc, the exact number of 
TOC records can be passed on. If a large predefined number of TOC records is 
used, then the application should check for the error 
MCIERR_INVALID_BUFFER. If this error is returned, then the number of 
TOC records was to small to hold all of the tracks. If this error is returned then 
the pBuf buffer is filled with as much track information as it could hold. By 
query the number of tracks the application can avoid receiving this error. 

Now that you know how to get the table of content information for the cur¬ 
rently loaded disc let us describe this information for each track. For each tack 
the following attributes are returned. 

• ulStartAddr: The Redbook starting address of the track in MMTIME 
units. 

• ulEndAddr: The Redbook ending address of the track in MMTIME 
units. 

• Control: Control information contained in the high nibble of the byte. 

> 00x0: 2 audio channels without pre-emphasis 

> 00x1: 2 audio channels with pre-emphasis 

> 10x0: 4 audio channels without pre-emphasis 

>10x1: 4 audio channels with pre-emphasis 

> 01x0: data track 

> 01x1: reserved 

> llxx: reserved 

> xxOx: digital copy prohibited 

> xxlx: digital copy permitted 

• usCountry: Country.(currently al 0s) 

• ulOwner: Owner, (currently al 0s) 

• ulSerialNum: Serial number(currently al 0s) 

The information supplied by the MCI_GETTOC command provides applica¬ 
tions with individual track information. This track information can be used for 
a number of applications such as providing for better display of track informa- 
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tion to end users in a CD jukebox application. This information could also be 
stored in a database with the CD Universal Product Code (UPC) and ID as the 
unique CD identifiers. The CD and tack information could then be retrieved 
later. 

The UPC and ID together should be used to identify CDs. This is because 
neither one by itself is unique. The UPS is a serial number assigned to the CD 
by the disc manufacturer. It is a binary coded decimal (BCD) number. 
Unfortunately the UPC is not supported by all disc manufacturers nor can it be 
read by all CD drives. 

The ID is 8-bytes of data and is made up of the following: 

• Starting track address 

• Number of tracks 

• Lead-out track address 

The ID is intended to represent a unique ID for the CD, but as you can see 
there is a possibility for duplicate disc IDs. Both the UPC and ID can be 
obtained from the CD device instance using the info command. 


“info cdl ID wait” 
“info cdl UPC wait” 


The identification of a CD disc is particularly important when the material 
on the disc is relevant to some other media such as video or to the application. 
If the disc is ejected by the user it might be necessary to identify the previous 
CD with the new CD inserted. This is where the UPC and ID can help. The 
application should keep the UPC and ID of the disc it is working with. If the 
disc is ejected, the application can compare the UPC and ID of the newly 
inserted disc with that of the UPC and ID it was working with. It is the respon¬ 
sibility of the application to determine the identity of the disc. MMPM/2 does 
not verify that the same disc that was ejected is reinserted. In fact in some sit¬ 
uations it may not matter what disc is in the drive. 

One item to consider for all applications utilizing the CD audio device is to 
determine if there is a disc present. The status media present command 
should be used to determine if a disc is in the CD drive. If this command 
returns FALSE then there is no disc in the drive. 


“status cdl media present wait” 
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CD-ROM devices also have varying capabilities when it comes to ejecting of 
the CD disc via software. To determine if a CD-ROM device can eject the disc 
use the following commands: 

“capability cdl can eject wait” 

“capability cdl can lockeject wait” 

These commands determine whether the disc can be ejected and whether 
the ejection button could be locked or disabled. Locking of the eject button is a 
good thing to do when the application can not run without the CD disc that is 
currently loaded. To lock the eject button of the CD drive use the following 
command: 

“set cdl door locked wait” 

Before the application shuts down or closes, it should unlock the CD device 
eject button. 
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INTRODUCTION 


Along with the functional interfaces for MMPM/2, there are a set of multime¬ 
dia user interface controls. The user interface controls available are secondary 
windows, graphic buttons, and circular sliders. These multimedia controls will 
help application developers create multimedia applications easier and more 
consistent with other MMPM/2 applications. 

These controls are modeled after a home stereo receiver unit. The stereo 
receiver has a frame with some number of knobs and push buttons. 



Figure 9-1. Home Stereo Unit 
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The knobs are used for tuning in a particular radio station. They are also 
used for setting the balance, treble and bass. The push buttons are used to 
mute/unmute and to set AFC. These home entertainment user interfaces are 
represented by the secondary window, circular sliders and push buttons. This 
section will provide a description of each control and examples on how to use 
the controls. 


SECONDARY WINDOWS 


As mentioned above, the secondary window provides the frame in which circu¬ 
lar sliders and push buttons are contained. The window itself provides for the 
standard set of PM window services such as sizing, moving, minimizing, maxi¬ 
mizing, closing, and resizing. Since the secondary window functions are so 
much like normal PM dialog window functions, it is easy to program them. 

The secondary window functions of MMPM/2 provide functions similar to 
standard PM dialog windows. The additional services that they provide are siz¬ 
able and scrollable dialog interfaces. The secondary window has two frame 
windows. The first frame window is the standard frame which provides the 
standard set of services. These services include; moving, sizing, minimizing, 
maximizing, and closing. In addition to the standard set of services, it also pro¬ 
vides for the resizing of the window to the default size. 

The set of secondary window APIs is defined in the section Appendix D: 
Secondary Windows. 


MMPM/2 WINDOW CONTROLS 


Since the programming model of MMPM/2 is an extension to the PM program¬ 
ming model, it is natural to assume that there are extensions to the window 
controls of PM for MMPM/2. The two extensions to the PM window controls are 
graphic buttons and circular sliders. The next two sections describe how to set 
up and manipulate these new controls. These controls allow multimedia appli¬ 
cations to provide a consistent set of multimedia controls that are supplied as 
part of the MMPM/2 toolkit and MMPM/2 runtime. A complete definition of the 
parameters for the messages for graphic buttons and circular sliders can be 
found in the MMPM/2 Programming Reference. 



Graphic Buttons 
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The graphic button provides the user with a interface like a push button. It is 
different than a normal push button for a number of reasons. The first reason 
is that it can display text, or graphics or both. It remains in its changed state 
after the user has clicked on it. 


Mute 


Figure 9-2. Graphic Button 

Graphic buttons have a number of styles, owner notifications and Control 
messages. The styles define the graphic button when it is created. The owner 
notifications are sent to the owner of a graphic button when the state of the 
button changes. The control messages are sent to the graphic button to change 
or manipulate the state or action of the button. 


Style 


Graphic buttons have eight styles available to them. They are: two state, ani¬ 
mated, and hilited. The following state defines are used on the 
WinCreateWindow API or in a dialog resource. 

• GBS_ANIMATION: Creates an animated graphic button that displays a 
series or bit maps. Display of the series is handled like a circular list; 
after the last bitmap in the series is displayed, the first bitmap in the 
series is displayed and so on. The animation sequence continues until the 
message GBM_ANIMATE is sent to the graphic button window owner 
with MP1 set to FALSE. 

• GBS_AUTOANIMATION: Creates an animated graphic button that 
automatically toggles its animation from off to on, or from on to off, when¬ 
ever the user clicks on it. Usually, when the button’s animation is off. the 
button is selectable. Conversely, when the animation is on, an action is 
being processed. This style is similar to the GBS_AUTOT WO STATE 
style. 
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• GBS-TWOSTATE: This flag creates a graphic button that has two 
states: up and down. When the button is in the up state, this means the 
button is selectable. When the button is in the down state this means an 
action is being processed. The up state for the button has the button 
bitmap drawn above the window owner. The down state for the button 
has the button bitmap drawn below the owner window. 

• GBS_AUTOTWOSTATE: Creates a two-state graphic button that auto¬ 
matically toggles its state from up to down or down to up whenever the 
user clicks on it. No messages from the owner are required for the button 
to toggle its state. 

• GBS_HILITEBITMAP: Creates a graphic button that displays a differ¬ 
ent bit map when the button is in a highlighted paint state. The high¬ 
lighted paint state occurs when the user presses the mouse button while 
the pointer is over the graphic button (or the user holds the spacebar 
down while the graphic button has the focus). This bitmap is set by the 
GBM_SETBITMAPINDEX message with GB.HILITE as the specified 
index to change. 

• GBS__DISABLEBITMAP: Creates a graphic button that displays a dif¬ 
ferent bit map when the highlighted paint state of the button is disabled. 
This bitmap is set by the GBM_SETBITMAPINDEX message with 
GB_DISABLE as the specified index to change. 

• GBS_3D_TEXTRECESSED: Creates a graphic button that has three- 
dimensional text. The text z-order is below the face of the button. The 
main body of the text is black, and its bottom and right edges are white. 

• GBS_3D_TEXTRAISED: Creates a graphic button that has three- 
dimensional text. The text z-order is above the face of the button. The 
main body of the text is white, and its bottom and right edges are black. 


Owner Notifications 

Owner notifications provide the window owner of the button with WM_CON- 
TROL messages whenever the state of the button changes. At the same time 
the window owner gets this message, the application message queue also 
receives this message. The window owner gets the message via the 
WinSendMsg API. The synchronous message (to the window owner) is provid¬ 
ed for cases when synchronous knowledge of the state change is required. The 
application notification (asynchronous) provides for the normal notification 
process, whereby the application can perform some action on a button state 
change. 
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• GBN_BUTTONUP: The graphic button is changing to an up paint state 
from either a down or highlighted paint state. 

• GBN_BUTTONDOWN: The graphic button is changing to a down paint 
state from either an up or highlighted paint state. 

• GBN_BUTTONHILITE: The graphic button is changing to a highlight¬ 
ed paint state from either an up or down paint state. 


Control Messages 

Along with the styles and owner notifications, there are a set of control mes¬ 
sages for controlling graphic buttons. This controls can be used at anytime by 
the graphic button window procedure to control that actions of the graphic but¬ 
ton. These controls might be used in response to the state change messages, in 
the case of manual buttons. They might also be used to set up the characteris¬ 
tics of a animated button; such as the animation rate and starting bitmap 
index. These messages are also used to query the state of the button, in the 
case of auto graphic buttons. These messages are sent to the window handle of 
the graphic button using the WinSendMsg APIs. Each message is describe 
and a description of its two parameters (paraml and param2). 

® GBM_ANIMATE: Sets the animation of an animated graphic button to 
start or stop at the first bit map in the series or at a bit map within the 
series. 

• GBM_QUERYANIMATIONACTIVE: Gets the animation state of an 
animated graphic button. 

• GBM__SETANIMATIONRATE: Sets, in milliseconds, the period 
between bitmap updates for an animated graphic button. 

• GBM_QUERYANIMATIONRATE: Gets the animation rate that is set 
for an animated graphic button. 

• GBM_SETSTATE: Sets a two-state graphic button to up or down, or 
toggles its state. 

• GBM_QUERYSTATE: Gets the state of a graphic button. Note: For a 
graphic button that does not have a two-state style, its state is always 
considered to be “up.” 

• GBM_SETBITMAPINDEX: Sets the bit map index to use for the vari¬ 
ous states of the graphic button; up, down, highlighted, not highlighted, 
beginning of animation series, end of animation series, or current state 
(refers to either the up or down bitmap). 
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• GBM_QUERYBITMAPINDEX: Gets the bitmap index used for a par¬ 
ticular button state. 

• GBM_SETTEXTPOSITION: Sets graphic button text position above or 
below the bitmap. 

• GBM_QUERYTEXTPOSITION: Gets graphic button text position rela¬ 
tive to the bitmap. 

• GBM_SETGRAPHICDATA: Sets the graphical data (graphic button 
text, bitmaps) for a graphic button and erases all previous data relating to 
the state of the button. 


Animated Button 

Animated buttons display a sequence of bitmaps one after another. The rate of 
the animation sequence is controlled by the GBM_SETANIMATIONRATE 
message. This rate is in terms of milliseconds between bitmaps. Animated but¬ 
tons can be displayed in either auto mode or manual mode. Auto mode (style is 
GBS_AUTOANIMTAION) toggles the state of the animation from on to off 
and off to on via user interaction without owner window intervention. 



Figure 9-3. Animated Graphic Button 

Two-State Button 

Two state buttons provide the look of a push button that contains an up and 
down state. The meaning of the up and down states are up to the application. 
The normal interpretation is that the up state indicates that the button is 
selectable. The down state usually indicates that an actions or operations is 
being performed. Like the animated button, there are both manual and auto 
modes. 
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Circular Sliders 

Circular sliders model the knobs on electronic devices such as a stereo system. 
These controls provide the same functionality as the PM linear slider, but pro¬ 
vide a more multimedia appearance. These knobs also allow for better utiliza¬ 
tion of PM space. This is important in multimedia, because multiple knobs or 
sliders are probably required to model or control a multimedia device. 



Figure 9-4. Circular Slider 


Styles 


The style of the circular slider is relatively set. The application can enable or 
disable certain features, but overall the circular slider is a circle with tick 
marks and the current dial setting in the middle. The following list defines the 
styles for the circular slider. 

• CSS_NOBUTTON: Prevents the display of the + and - value buttons. 

• CSS_NOTEXT: Prevents the display of a window title beneath the dial. 

• CSS_NONUMBER: Prevents the display of a scrollable numeric value 
on the dial indicating the dial’s value. 

• CSS_POINTSELECT: Enables tracking of the dial’s value with the 
mouse. 

• CSS_360: Extends the scroll range of the dial to 360 degrees. When this 
style is set, CSS_NONUMBER and CSS_NOBUTTON styles are auto¬ 
matically set. 
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• CSS_MIDPOINT: Enlarges the mid-point and end point tick marks. 

• CSS_PROPORTIONALTICKS: Enables the length of the tick marks to 
be calculated as a percentage of the dial’s radius. 

Owner Notifications 

The circular slider has a set of notification messages it sends to the window 
owner of the slider. These message, like that of the graphic button, notify the 
owner window that the sate of the slider is changing. 

• CSN_SETFOCUS: The circular slider is gaining the input focus. 

• CSN.QUERYBACKGROUNDCOLOR: The circular slider is about to 
be painted. 

• CSN_CHANGED: The value of the slider is changed. 

• CSN_TRACKING: The value of the slider is being tracked by the mouse. 

Control Messages 

Like the graphic button, the circular slider supports a set of control messages 
for setting and querying the slider. These controls are: 

• CSM_SETINCREMENT: Sets the scroll and tick mark increments of 
the circular slider. 

• CSM_QUERYINCREMENT: Queries the increments used to scroll the 
value and to draw the tick marks. 

• CSM_SETRANGE: Sets the range of values for the circular slider scale. 

• CSM_QUERYRANGE : Queries the range of values for the circular slid¬ 
er scale. 

• CSM_SETVALUE: Sets the current value of the circular slider. 

• CSM_QUERYVALUE: Queries the current value of the circular slider. 

• CSM_QUERYRADIUS: Queries the current radius of the circular 
slider. 

• CSM_SETBITMAPDATA: Replaces the bitmaps used for the plus and 
minus buttons. The optimal size for these bitmaps is 10*10 pels. 
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SAMPLE 


Provided on the diskette with this book is a sample of how to use secondary 
windows, animated push button, circular slider and two state push button. 
This sample code provides a very simple PM application for playing the CD 
audio device. The controls presented are a circular slider for control the vol¬ 
ume, an animated play button, and a mute push button. 



Figure 9-5. Sample Application 

Dialog Initialization 

The dialog initialization sets up the three controls and opens a CD audio device 
instance. Because we need a window handle for each of the controls, we use the 
WinWindowFromID call to get one for each control. 


^^ic^^^^i^^^'k'k'k-k-k'k'k'ki^'k'k'k'k-k-k'k'k'k'k'k'k'k-k-k'k-k-k-k'k-k'k-k'k^-k-k'k-k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k j 


/* Initialize the controls */ 
/* 1) Get the window handles for the three controls */ 
/* 2) Set up the animation rate for the play button to 100 */ 
/* milliseconds between bitmaps */ 


/* 3) Set the text “Mute” for the Mute button to appear below */ 
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/* the button. */ 

/* 4) Set the range of the circular slider from 0 to 100 and */ 

/* set its initial value to 75 */ 

/***************************************************************j 

hwndPlay = WinWindowFromlD(hwnd, ID_GPB_PLAY); 
hwndMute = WinWindowFromID(hwnd, ID_GPB_MUTE); 
hwndCirSlider = WinWindowFromID(hwnd, ID_CS_V0LUME); 


The next part of the initializion, takes care of any control specific initializa¬ 
tion. The Play button animation rate is set to 100 milliseconds between 
bitmaps.The Mute button has the text position below the button. The circular 
slider has the volume range set (0 to 100) and the initial volume setting to 75. 


WinSendMsg (hwndPlay, 

GBM_SETANIMATI0NRATE, 
MP FROM L0NGC100L), 
NULL); 

WinSendMsg (hwndMute, 

GBM_SETTEXTP0SITI0N, 
(MPARAM)GB_TEXTBEL0W, 
NULL); 

WinSendMsg (hwndCirSlider, 
CSM_SETRANGE, 
MPFROMLONG(OL), 
MPFROMLONG(IOOL)); 


WinSendMsg (hwndCirSlider, 
CSM_SETVALUE, 
MPFR0ML0NG(75L), 
NULL); 


The final part is the opening of a CD instance and set its volume to 75 per¬ 
cent. If the open command fails then the mciGetErrorString is called to 
return a error string describing the failure. 


/* Open the cd audio device and set the initial volume to */ 

/* 75 percent. If there is an error on the opening of the */ 

/* device then exit this application. */ 

/***************************************************************/ 
usReturnLength = 128; 
pszReturnString[0] = ‘\0’; 

rc = mciSendString(“open cdaudio alias CD1 wait shareable”, 
pszReturnString, 
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usReturnLength, 
hwnd, 

5); 

if (rc) 

{ 

mciGetErrorString(rc, pszReturnString, 127); 
e x i t (1); 

} 

el se 
{ 

usReturnLength = 128; 
pszReturnString[0] = *\0'; 

rc = mciSendString(“set CD1 audio on volume 75 wait”, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 


Play Button Control 

The play button control code toggles between playing and paused states. If the 
animation state of the play button is FALSE, then send the play command to 
the CD device. An animate message is sent to the play button, and it resets the 
animation state variable ( usAnimate ) to TRUE. If the animation state is TRUE 
then a pause command is sent to the CD device instance and a stop animation 
message is sent to the play button. This code is trigger off of the user clicking 
on the play button. 


I ******************************* ********** ********************j 


/* The play button was pushed. If the current state is */ 
/* animating then stop the animation and pause the CD device */ 
/* If the current state is not animated (not playing) then */ 
/* start the animation and send the play command to the CD */ 
/* device. */ 


!*************************************************************/ 
case ID_GPB_PLAY: 

if (usAnimate==FALSE) 


usReturnLength = 128; 
pszReturnString[0] = ‘\0’; 
rc = mciSendString(“pi ay CD1 notify”, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 

WinSendMsg(hwndPI ay, 
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GBM_ANIMATE, 

MPFROMSHORT(TRUE), 

FALSE); 

usAnimate=TRUE; 

} 

el se 
{ 

usReturnLength = 128; 
pszReturnString[0] = *\0 *; 
rc = mciSendString(“pause CD1 wait”, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 

WinSendMsg(hwndPlay, 

GBM_ANIMATE, 

MPFROMSHORT(FALSE), 

FALSE); 

usAnimate=FALSE; 

} 

break; /* end case ID_GPB_PLAY case */ 


Mute Button Control 

The mute button control code handles the mute or unmute of the CD audio 
device volume. This button is a two state button with different bitmaps for the 
two states. When the state is toggled from up to down or down to up the mes¬ 
sage GBM_SETGRAPHICDATA is sent to the graphic button. The GBTNC- 
DATA data structure is filled in with the text and bitmap to be displayed. The 
address to this data structure is passed as MP1 on the GBM_SETGRAPHIC- 
DATA message. Since this message erases all previous data relating to the 
state of the button a GBM_SETSTATE message must also be sent to set the 
state of the button. Notice that to mute the volume the set command with vol¬ 
ume set to 0 is used. This requires the volume before the mute command to be 
saved. This volume value will be used to reset the CD audio device instance 
volume during the unmute action. 


f*i?-kic*i(****-k'k-k'k'k'k-k'k-k-kJc-k'k-k'k'k'k'k-k-k-k-k'k'k'k'k'k'k'k-k'k-k-k'k'k-k-k'k'k-k'k'k'k-k-k-k-k-k-k-k-k/ 

/* The mute button was pushed. If the current state is muted */ 

/* then reset to unmuted and change the state and bitmap of */ 

/* the mute button. If the current state is unmuted then set */ 

/* the state of the button to down and change the bitmap. */ 

/■k^-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k-k'k'k'k-k'k'k'k'k'k^c-k-k'kic'k'k'kiz'k'k'k'k'k'k'k'k'k^'k'k'ki’C'k'k'k/ 

case ID_GPB_MUTE: 
switch (usMute) 
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case TRUE: 

pBuff = itoa(usVolume, pszBuffer, 10); 
usReturnLength = 128; 
pszReturnString[0] = ‘\0’; 

strcpy(pszCommandString, “set CD1 wait audio on volume “); 
strcat(pszCommandString, pBuff); 

re = mciSendString(pszCommandString, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 

usMute=FALSE; 

/************************************************/ 

/* Set the bitmap of the mute button to the down*/ 

/* bitmap and set the state of the button to */ 

/* down */ 

j ■k-k-k'k^-k-k-k-k-k^'k'k-k'k-k'k'k-k-k'k-k'k-k-kic-k-k'k-k'k'k-k-k-k'k-k'k-k'k-k'k'k'k'k-k'k'k j 

gbtncdata.usReserved = GB_STRUCTURE; 

gbtncdata.pszText = “Mute”; 

gbtncdata.hmod = hmod; 

gbtncdata.cBitmaps = 1; 

gbtncdata.aid Bitmap[0] = ID_BMP_MUTEUP; 

WinSendMsg (hwndMute, 

GBM_SETGRAPHICDATA, 

(MPARAM)&gbtncdata, 

0L); 

WinSendMsg (hwndMute, 

GBM_SETSTATE, 

(MPARAM)GB_UP, 

(MPARAM)TRUE); 

break; 

case FALSE: 

usReturnLength = 128; 
pszReturnString[0] = *\0’; 

rc = mciSendString(“set CD1 volume 0 audio on wait”, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 

usMute=TRUE; 

/************************************•*•*•*•-*•-*■-*■•*■•*■■*•■*•-*••*-/ 

/* Set the bitmap of the mute button to the up */ 

/* bitmap and set the state of the button to up */ 

J'k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k'k'k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kl 

gbtncdata.usReserved = GB_STRUCTURE; 
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gbtncdata.pszText = “Mute”; 

gbtncdata.hmod = hmod; 

gbtncdata.cBitmaps = 1; 

gbtncdata.aidBitmap[0] = ID_B M P_M U T E D N; 
WinSendMsg (hwndMute, 

GBM_SETGRAPHICDATA, 
(MPARAM)&gbtncdata, 

OL); 

WinSendMsg (hwndMute, 

GBM_SETSTATE, 
(MPARAM)GB_DOWN, 
(MPARAM)TRUE); 

break; 

} 


break; 


Circular Slider Control 

The circular slider control handles changes in volume commands. Each change 
or movement on the circular slider will cause a CSN_TRACKING or 
CSN_CHANGED messages to be sent. The code will then request the current 
circular setting. It will then send a set command to change the volume. 


/*****************************************************************/ 
/* Handle the volume ticks and changes in the volume slider */ 

/*****************************************************************/ 
case WM_C0NTR0L: 

switch (SHORTlFROMMP(mpl)) 

{ 

case ID_CS_VOLUME: 

switch (SHORT2FROMMP(mpl)) 

{ 

case CSN_CHANGED: 
case CSN_TRACKING: 

if (usMute == FALSE) 

{ 

WinSendMsg (hwndCirSlider, 

CSM_QUERYVALUE, 

&usVolume, 

NULL); 

pBuff = itoa(usVolume, pszBuffer, 10); 
usReturnLength = 128; 
pszReturnString[0] = ‘\0’; 
strcpy(pszCommandString, 

“set CD1 wait audio on volume “); 
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strcat(pszCommandString, pBuff); 

rc = mciSendString(pszCommandString, 
pszReturnString, 
usReturnLength, 
hwnd, 

5); 


break; 
} 




10 


MMPM/2 Tips and Techniques 


INTRODUCTION 


This chapter provides tips and techniques for MMPM/2 application program¬ 
ming, and system usage information. These tips and techniques cover undocu¬ 
mented programming features, common MMPM/2 usage, sharing system 
resources with WinOS2, trouble shooting, and system and application perfor¬ 
mance improvements. Although some of the items discussed here were covered 
to some extent, in other chapters; this chapter consolidates these and some 
new ones into a collection of useful MMPM/2 tips and techniques. 


MCI PROGRAMMING TIPS 

How to Detect if MMPM/2 is Installed on a System 

Most applications can be written to take advantage of multimedia if it exists in 
the system. Unfortunately not every PC is multimedia enabled. That is, they 
lack audio hardware. Furthermore, not every multimedia enabled PC with 
OS/2 2.0, 2.1 or Warp installed has MMPM/2 installed. Remember MMPM/2 is 
an optionally installable feature. Therefore, applications need to determine if 
MMPM/2 is installed in the system and if it is what multimedia hardware is 
available. 

To determine whether MMPM/2 is installed in the system applications can 
do one of two things. The first is to look for the environmental variable 
MMBASE. This environment variable is used by MMPM/2 to locate DLLs, 
DSP task modules and other system files. This variable is setup during the 
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installation of MMPM/2. The second method to determine if MMPM/2 is 
installed is try to DosLoadModule MDM.DLL from the MMOS/2 directory. If 
these tests fail then MMPM/2 is not installed in the system. 

Once it is determined that MMPM/2 is installed in the system, applications 
can make SYSINFO calls to determine what type of multimedia devices are 
available. The SYSINFO message with the quantity keyword will tell how 
many of a particular device type are installed in the system. 

String Interface vs. Procedural Interface 

MMPM/2 applications have two options when it comes to MCI interfaces; 
procedural or string. Both interfaces provide the same level of functionality, 
with some minor exceptions(string interface functions are a subset of the 
procedural). Most of these differences in functions are SYSINFO commands 
not supported by the string interface. What the string interface does provide 
above the procedural interface is device type independence. That means 
MMPM/2 applications using the string interface do not have to worry about the 
exact data structure and flags required by a particular device type. The string 
interface makes the conversion from string commands and keywords to flags 
and data structure. By using the string interfaces, applications remain much 
more independent of the device hardware and the device type interfaces. 

One concern about using the string interfaces is the performance hit because 
of the string parsing that has to take place. The MMPM/2 string parser has 
been optimized so as to provide as minimal an impact on performance as possi¬ 
ble. String command tables are cached and the command tables are scanned 
efficiently for the correct command to parse. To help improve string command 
parsing even more, applications should issue string commands in lowercase. 

Wait vs. Notify 

All MCI commands operate in either synchronous or asynchronous mode. The 
mode to choose depends on the type of command. Commands that are 
processed quickly and that return information should be executed synchro¬ 
nously. To specify synchronous operation, applications must specify the wait 
flag. Commands that can potentially take a long or indefinite period of time to 
complete should operate in an asynchronous manner. To specify asynchronous 
operation, applications must specify the notify keyword or flag. 

In addition, commands requiring return information should use the synchro¬ 
nous mode of command execution. From the string interface, this is the only 
mode in which information will be returned. From the procedural interface the 
data structure passed in must remain as a valid data area for MMPM/2 to copy 
return information into. Since most if not all MCI commands returning infor¬ 
mation are quick, the wait keyword is recommended. 
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If a MMPM/2 device instance is opened and then played, a number of process¬ 
ing steps must take place. The media device element is opened and read. The 
data streaming buffers are allocated and filled. To ensure that play or record 
commands take place with as little delay as possible, the cue command should 
be issued before the play or record. The cue command prerolls the media device 
instance, so that it is in a ready-to-play or a record state. The file is open and 
read. The data stream is completely setup and for the playback case the buffers 
are filled. 

Digital video files are automatically prerolled on a playback. This is to 
ensure properly synchronized playback or audio and video. MIDI and audio are 
not implicitly prerolled. It would make sense to preroll (cue) audio to speed up 
the play responsiveness (play). 

Using the from option on play for audio or video, discards any prerolled 
data. Use the seek, cue, play combination to achieve the same result and to 
increase responsiveness to the play operation. 


“seek waveaudio to 3000 wait” 
“cue waveaudio output wait” 
“play waveaudio wait” 


This example seeks to a position “3000” within the waveaudio data, then 
cues the device for output, then plays the waveaudio data. Keep in mind that 
when a seek is performed, that the position seeked to is an absolute position, 
with relation to the currently set time format. 

Remember that after a load command a new cue command should be 
issued. 

Setpositionadvise Frequency 

The setpositionadvise command allows applications to request periodic noti¬ 
fications during playback and recording. This command is very useful for pro¬ 
viding feedback on the timing and progress of a playback or recording. Like all 
functions, this command does have a certain about of processing overhead 
involved. Therefore care must be used when deciding on the frequency of the 
setpositionadvise messages. The more frequent the setpositionadvise mes¬ 
sage the more processing is required by MMPM/2. A frequency rate of less than 
100 milliseconds is certainly inadvisable. The bigger the frequency the less of 
an overhead this command has on the system. 
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Applications should try various frequency rates during testing, starting as 
high as possible, to determine the best rate for the application and the system. 
One rule that may help is that external devices such as CD audio and 
Laserdiscs, should have their frequency set higher than normal streaming 
devices. This is because external devices are not going to be able to report their 
position with as much precision as an internal streaming device. Frequency for 
external devices should probably be set on the order of a second or two. 
Internal streaming devices should probably be set on the order of a half second 
and moved up or down during performance tuning. 

Setcuepoint Message 

The setcuepoint command allows applications to set one time notification 
event. Unlike the setpositionadvise message, a device can have multiple out¬ 
standing cuepoints. Each outstanding cuepoint requires memory and process¬ 
ing time. Once a cuepoint is enabled, it remains enabled until the application 
disables the cuepoint. If a data element is played and then seeked to the start, 
the same cuepoint, if not disabled, will be triggered again by each subsequent 
play. An application should always disable, or turn off, a cuepoint once it is no 
longer needed. 

All devices have a limit as to the number of outstanding cuepoints. One way 
to minimize the number of outstanding cuepoints is to set a new cuepoint when 
an outstanding cuepoint is reached. This requires some thought because cue- 
points that are very close in time may not be able to be set. Again this is a 
function that will require some performance tuning during application develop¬ 
ment. A good rule is to have a small number of outstanding cuepoints. 

Setting and Querying MMPM/2 Workpath 

Recording operations involve temporary resources, such as files. These tempo¬ 
rary files can grow quite large depending on the recording time and the data 
type of the file. MMPM/2 places all temporary files in the sub-directory denot¬ 
ed by the MMPM/2 workplace variable. This workpath can be queried and set 
using the mciQuerySysValue and mciSetSysValue APIs. The sysvalue to 
query and set is the MSV_WORKPATH value. Before beginning a recording of 
audio or video it is recommended that applications check the workpath vari¬ 
able for the temporary file path. Once this path is determined then a check for 
free disk space should be made to determine how much audio or video could be 
recorded. The amount that could be recorded will depend on the data type of 
the media to record. Remember that the amount required is twice the amount 
of the file. This is necessary because MMPM/2 must maintain the real file as 
well as the temporary file. 
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Open with o Data Element vs. Open then Load 

As was discussed in chapter 5, it is recommended that an application open the 
audio device with a data element if possible. This improves general perfor¬ 
mance, because if the device is opened without a data element, the device is set 
to a default state, normally record for audio devices. If you wish to play back 
audio and load a file, any buffers, or temporary files that may have been allo¬ 
cated/created will have to be freed/closed, and new buffers allocated to match 
the content type of the file being loaded. If this step, is done during the open, 
then memory/files are only manipulated once and the audio device driver will 
not have to initialize the hardware twice. 

Load and Reload 

Once you have the audio device open and a data element loaded, it is recom¬ 
mended instead of closing and reopening the device, that a load be performed. 
This is different then the previous example, because the device has already 
passed through the process of initializing data buffers already. Loading a data 
file will save on some internal housekeeping within MMPM/2. Furthermore, if 
at all possible and applicable to the type of application being developed, try to 
create the content in the same format (i.e., if some recording have been made 
at 22.050Khz, 8-bit, mono, then try to create as many as possible in this for¬ 
mat). Loading in files of the exact format one after another will cause the data 
buffers used for the previous data element to be reused automatically by 
MMPM/2 streaming subsystem and the audio device will not have to be 
reinitialized. 

Optimizing Use of MCI "Set" Command for Audio Devices 

The MCI supports changing more than one setting at a time from within a 
command string. If editing audio in memory, or to switch to a different format 
for recording it is possible to change as many of the format settings necessary, 
at once. For instance, to set the device state to 44.1Khz, 16-bit, Stereo, send 
the following string: 


set waveaudio samplespersec 44100 bitspersample 16 channels 2 wait” 


or, to change just the sampling rate, and change to IBM ADPCM mode: 


“set waveaudio samplespersec 22050 format tag ibm adpcm wait 
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If you have an alias already created for the audio device, then substitute it 
where we have used “waveaudio.” Other setting changes can be performed 
from within one command string as required. 


GENERAL MMPM/2 PROGRAMMING TIPS 

Application Stack Size 

MMPM/2 applications should use, at a minimum, 16k. Since OS/2 is a virtual 
memory system, physical memory is used only when needed. That means that 
if a 16k stack is defined only the first 4k is allocated. The rest of the stack is 
not allocated until needed. Therefore a stack size of 32 to 64k is recommended. 
Errors such as traps in MMPM/2 DLLs (HHP, MDM MMPMCRTS, etc.) usual¬ 
ly indicate stack overflow. 

Multithreaded Applications 

MMPM/2 applications are extensions to Presentation Manager applications. 
Therefore they must process messages from PM as well as MMPM/2. 
Multimedia functions, unlike normal system functions, can take long periods of 
time to complete. For example playback, seek or recording. That is why these 
types of commands must be processed asynchronously with notifications sent 
back to the application upon completion or error. Secondarily, passdevice mes¬ 
sages arrive asynchronously and must be processed in a timely manner. For 
these reasons MMPM/2 applications should be multithreaded. One thread 
should handle the window queue to process messages in a timely manner to 
provide better system responsiveness. One or more other threads should han¬ 
dle the multimedia functions for the application. This type of application must 
be designed from the beginning with the thought of being multithreaded. 

General Performance Tips 

One of the most common uses for multimedia is the playing of audio clips. 
Audio clips can be associated with system events, errors, user action, help, 
tutorials, etc. It is also very common to play many different or similar clips 
over and over in an application. This could pose a performance problem if the 
sequence is open, play, close; is, repeated over and over. This is because 
resources are allocated on MCI device opens and resources are closed on MCI 
device close. This resource allocation need not occur repeatedly. Applications 
should open the device once and use the load command repeatedly. The load 
command will simply open new resources associated with the load element. 
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The load command can also be used in one of two modes; file element or 
MMIO handle. Using a file element (file name) on the load will cause the audio 
subsystem of MMPM/2 to utilize MMIO to associate an 10 proc with the file 
and then open the file through MMIO. This processing is part of the load com¬ 
mand processing. The second mode of the load command bypasses this process¬ 
ing because a handle to a MMIO element is passed in. This means that the 
application has already made the MMIO calls to identify the 10 proc and open 
the element. This process could have occurred at application startup or during 
other times while, the application was doing other things. This technique of 
passing a MMIO handle on the load command can also be used on the open 
command. This will decrease open processing times. Remember to open the file 
correctly (in some cases digital video expects the translate data flag to be set 
on, bad things will happen if not set on). 

Care should be taken when deciding on the data type of audio files. Not 
every audio card supports all of the compressed audio formats. Also the high 
quality audio sampling rates and bits per second are not always needed. 

As we presented in Audio Playback and Record , conversational speech 
can be recorded at either 8 or llKhz, 8-bit, Mono, and still retain good play¬ 
back quality. For recording music, however, generally it is wise practice to 
choose a higher sampling rate, and data width (16-bit). Stereo is not always 
essential, unless there are effects within the audio track that either use, or 
require, it. If what is being recorded is noisy, adjusting the gain on the 
AmpMixer will help eliminate some of the noise in the recording. Recording at 
44.1Khz is best when recording music for studio quality reproduction. 
Recording at 22Khz, 16-bit, mono will provide a good middle ground sound 
quality that will encompass all of normal speech, and most instrumental 
sounds. 

The other technique that will improve system performance and system 
resources is the use of the readonly flag when opening or loading a file for 
playback only. Normally MMPM/2 will create a temporary file if a audio or 
video file is not opened with the readonly flag. This is because without the 
readonly flag any data loaded into a device can be edited, and later saved, or 
updated back to a file. Since the readonly flag tells MMPM/2 that the file is to 
be used for playback only, this allows MMPM/2 to treat the file differently than 
the default mode for the device, which is read/write. This way MMPM/2 fore¬ 
goes having to open a temporary file, or managing any temporary resource. 

File Handles 

MMPM/2 set the number of file handles to 100 for each process that uses it. 
The DosSetRelMaxFH API is used. If the application process already has the 
number of file handles set to 100 or more than it is left at that number. If your 
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application issues the same DosSetRelMaxFH to some number greater than 
100 it will get an error return code. This error return code indicates that the 
number of maximum file handles is already greater than or equal to the num¬ 
ber specified. 

Non-multimedia Applications Running in Background 

MMPM/2 utilizes a special thread priority type exclusively for its internal use. 
During authoring or playback of multimedia content that require high data 
rates, performance in the system may vary, and can causes user-interface 
responsiveness problems in some applications. It is important to note that this 
type of scenario may only occur during times of high system load, unless 
absolutely necessary, applications should avoid the use of time-critical class, 
high level priority threads. Utilizing the printing subsystem under OS/2 may 
cause performance problems with multimedia programs running at the same 
time. 

Playing Audio and Movie Files From a Network Server 

MMPM/2 has support for guaranteed bandwidth reservation on a network. On 
most networks, data transfers are typically not guaranteed to occur within a 
specific time period. This can cause the remote playback of an audio file to 
breakup and this is very undesirable. Remotely playing movie files tend to be 
worse because of the required bandwidth to transfer video and audio data 
across a network. Quality of service, or QOS, is a term used to describe a 
feature of some networks that provides the ability to guarantee certain attrib¬ 
utes of data transfer across a network. Refer to the Using Multimedia I/O 
(MMIO) chapter for more details. 

CD-ROM Single Spin vs. Multi-spin 

When MMPM/2 was first developed, the variety of CD-ROM devices that are 
available today did not exist. The area of concern in utilizing and supporting 
the various types of CD hardware rely mainly on one major issue: throughput. 
The data transfer rate of the first generation, or single-spin CD-ROM drives 
was about 150KB/second. In 1992, there were several new CD-ROMs intro¬ 
duced which doubled this rate to 300KB, these were referred to as double-spin 
drives. In the past year, even newer drives with triple or quadruple the data 
rates of the original drives have become available. Double spin drives have 
become much the standard. Most manufacturers include these types of drives 
with their multimedia systems. Obviously, the faster the data throughput, the 
more complex the drive, and thus higher the price. 
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Data throughput of 150KB/sec is adequate for most audio playback, and so 
faster drives will not buy any significant gains. However, in reference to SMV, 
what type of CD-ROM drives to use when authoring data is very important. 
Take into consideration, not only the quality of the presentation, but the capa¬ 
bilities of the hardware that a typical customer for your software, has. Keep 
very much in mind that since the variety of CD-ROM drives may be leaning 
more towards the faster drives as a standard, that therels always a group of 
customer that may not have the capabilities to play back movies authoring at 
higher data rates. 

One way around this which has been done by some software developers 
already, is to “test” the capabilities of the CD-ROM itself when installing your 
software. In other words, have a sample data file that you read, track how long 
it took to read in, and then determine the data throughput rate via the follow¬ 
ing formula: 


Data rate = ( KBytes / seconds ) 


A very simple equation for determining the capabilities of the drive the soft¬ 
ware will be used on. The second part of this process is to include two sets of 
movies. One which has the movies authored at the slower data rate, and anoth¬ 
er with ones authored at a higher data rate. If possible, perhaps you can 
include both sets on one CD. When setting up the application, as part of the 
information about where data is stored, simply direct the paths to point to 
where the appropriate data for the drive just tested, are. Obviously, this whole 
process is dependent upon the type of application that is being created. This 
scenario, is one solution to supporting the hardware capabilities of the majority 
of possible customers. 

Compile Options for Optimization 

Using CSET++, use the /Ss switch because some of the MMPM/2 headers 
shipped in the toolkit use the // or C++ comments. 


TUNING MEMORY USAGE IN MMPM/2 AND RUNNING MULTIPLE 
MULTIMEDIA APPLICATIONS 


The maximum number of multimedia applications running on a system can 
vary depending on the amount of memory in the system and the number of 
other applications running in the system. Each type of MMPM/2 media device 
uses a different amount of memory, and this even varies depending on many 
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things, for example, waveform audio file length, video frame size. The media 
devices the transfer data from secondary storage or memory to a device usually 
use the streaming subsystem for this purpose. The streaming subsystem allo¬ 
cates the data buffers and other memory used in this process. The stream sub¬ 
system also has a default maximum number of “streams” that can be created 
at one time. A “stream” is a set of data buffers used to transfer data of one or 
more media types from one device to another. The number of data buffers ad 
amount of memory in each data buffer varies according to many factors. The 
maximum number of streams, as well as some other parameters can be 
changes or tuned for a system. 

The streaming subsystem can be tuned for a machine depending on the 
amount of memory available and the number of multimedia applications that 
will be simultaneously running on a system. There are two ways to tune these 
values. The first is to set them in the CONFIG.SYS file on the 
DEVICE=C:\MMOS2\SSMDD.SYS statement. The second is to use the 
MMSTREAM environmental variable to change the amount of resources that 
are used and reserved by the stream subsystem (available on OS/2 Warp). The 
MMSTREAM environmental variable will take precedent over the config.sys 
device statement parameters. The defaults for each of these resources will 
dynamically changes depending on the amount of memory in the system. 
Currently, MMPM/2 has defaults for 4MB or less, 8MB or less, greater then 
8MB systems. 

The 4MB defaults severely limit the number of multimedia applications that 
can run at a time. This can cause error messages to be displayed when too 
many multimedia applications are started. Some of the following errors can be 
caused by this condition: 


Error 

Error String 

Suggested Action 

5651 

“Too many streams active.” 

Increase /S:xxx parameter 

5621 

“Error loading a stream handler.” 

Increase /S:xxx parameter 

5649 

“Error allocating memory from heap.” 

Increase /H:xxx parameter 

5010 

“Cannot load MMPM2 driver.” * 

Increase /P:xxx parameter 


* This is a “catch-all” error return code, problem maybe something else. 


Table 10-1. Error Table 
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If the environment variable, MMSTREAM, is used, then it must be set 
before any multimedia applications are running, this includes system sounds. 
Systems sounds must be disabled and the system rebooted before they will be 
detected and used as the default by MMPM/2. If system sounds is not enabled, 
and a multimedia application is already running, MMSTREAM will not be 
detected until this application is terminated and restarted. The following list of 
parameters can be used on the device statement for SSMDD.SYS or the envi¬ 
ronmental variable MMSTREAM: 


Parameter 

Description 

<=4MB 

<=8MB 

>8MB 

/S:sss 

Specifies the maximum number of 
streams that can be created at one 
time. The valid range for sss is l-to-64. 

3 

6 

12 

/H:hhh 

Specifies the maximum amount of 
heap space in (KB). The valid range 
for hhh is 16-to-256. 

32 

64 

64 

/E:eee 

Specifies the maximum number of 
events that can be enables per stream. 
The valid range is l-to-1024. 

10 

20 

32 

/P:ppp 

Specifies the maximum number of 
processes that can create streams. 

The valid range is l-to-64. 

3 

6 

12 

/Q:qqq 

Specifies the maximum size of the 
event queue per process. The valid 
range is 2-to-1024. 

64 

64 

64 


Table 10-2. Tunable Parameters for Streaming Subsystem 


SYSTEM USAGE CONSIDERATIONS 

WINOS2 and Multimedia Support 

From release v2.1 of OS/2 and on, support for the multimedia extensions to the 
Windows environment is included in the product. If you are using OS/2 for 
Windows, this installation, they will already be set up by the installation 
process. Otherwise, to enable this support, drivers for multimedia devices 
under WinOS2® must be installed via the control panel applet in the WinOS2 
Main group. Support included in OS/2 (full product, including WinOS2) itself 
does not differ from the what is provided by Windows 3.1. However, there are 
things that the user and developer as well should keep in mind when using 
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WinOS2, or developing applications for MMPM/2. The reasons for why a devel¬ 
oper should be concerned with WinOS2 are related primarily with the concept 
of resource (or device) sharing within the system as a whole. 

WinOS2 (or OS/2 for Windows with Windows pre-existing installed) provides 
support three basic multimedia devices that the user will have direct control 
over: WaveAudio, MIDI, CD Audio. These devices can be accessed by the 
Media Player application. Other devices are installed into WinOS2, (like the 
MIDI MAPPER, etc.) but are primarily for use by other devices in that 
environment. 

WINOS2—Program Object Settings 

Since WinOS2 and OS/2 for Windows, both support multimedia under the 
Windows environment, it is important that the correct settings be made into 
the notebook of any object for Windows itself (Full Screen or Seamless) or any 
Windows application that has an object created for it. There are many settings 
that are affected, we will only discuss those that are directly correlated to mul¬ 
timedia under WinOS2, and how they affect MMPM/2. 

Here is the list of settings that will affect Windows multimedia running 
under OS/2: 


Setting 

Used For 

Set To 

HW_TIMER 

Hardware timer direct 
programming 

ON 

INT_DURING_IO 

Allow Timers to received during 

TO requests 

OFF 

IDLE_SECONDS 

Idle Time to allow before limiting 
sessions time-slice 

1 

IDLE_SEN SITIVITY 

Threshold for idle polling 

100 

VIDE 0_8 514_XGA_I OTRAP 

Allows faster access graphics 
hardware 

OFF 

video_retrace_emulation 

Disable video retrace (used for 
text-based applications) 

OFF 


The chart lists those general settings that allow for better performance of 
multimedia applications under the WinOS2 environment. The Used for col¬ 
umn indicates the use and benefit of having the setting set to the setting indi¬ 
cated in the Set to column. 
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WIN0S2 Audio Device Sharing Problems and Work-arounds 

There is one setting that was not included in the previous list because it bears 
special mention by itself. This setting is the AUDIO_ADAPTER_SHARING 
setting. This setting is provided only if the audio device driver installed for 
MMPM/2 includes a special Virtual Device Driver (VDD) for OS/2 Dos emula¬ 
tion. This setting allows the audio device driver under MMPM/2 to know if an 
application (or several applications), currently have access to the audio hard¬ 
ware in DOS or WinOS2 sessions. This facility allows for one application at a 
time to actively access the audio hardware, and not have it’s environment 
destroyed, in the middle of some operation, by another application. 

It is possible to restrict an application from accessing the audio hardware, 
by setting this setting to NONE. This will mean that the program object that 
has it is AUDIO_ADAPTER_SHARING setting set this way will be inhibited 
from accessing the audio hardware entirely. If the setting is set to 
REQUIRED, however, then this program object will be included in the process 
of ownership sharing of the audio hardware. 

Hardware 

SCSI vs. IDE 

In comparing SCSI and IDE hardware. There are some general functions and 
features unique to each, that must be considered. The following list below does- 
nlt make general assumptions or recommendations, but simply provides infor¬ 
mation about each which can be used to arrive at decisions for selecting hard¬ 
ware that can support multimedia. 

SCSI—Small Computer Standard Interface, was developed to allow manage¬ 
ment of multiple devices via one controlling mechanism. IDE—Integrated 
Drive Electronics, was developed to simplify the controller hardware on sys¬ 
tems, by placing the controlling mechanism onto the drive itself. Generally a 
controller for SCSI devices is an intelligent piece of hardware, possibly with a 
complete microprocessor unit and localize RAM (other than cache) to operate 
on. IDE controllers on the other hand mainly acts as routers for disk 
operations. 

Here is a list of features and functions of both types of drive systems: 


SCSI 

1. Intelligent Controllers. 

2. Up to 7 devices chained, per controller. 

3. Devices need not be similar. In other words, it is possible to have a hard 
drive, scanner, and CD-ROM device on the same chain. 
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4. Newer SCSI controllers provide secondary data caching storage. 

5. SCSI hard drives generally maintain a 256K to 1MB primary cache on 
board. 

6. Newer SCSI controllers support SCATTER-GATHER, a technique to 
improve overall throughput capacity. (1) 

7. SCSI hardware generally has a higher data transfer rate than IDE. 

8. SCSI hardware tends to cost higher than IDE hardware. 

9. SCSI hard drives are generally available in capacities ranging in the 
Gigabytes. 

10. SCSI devices are typically interrupt driven, while IDE devices typically 
use a polling method to transfer data. The polling method is not as effi¬ 
cient for multitasking operating systems like OS/2. 

IDE 

1. Passive Controllers, intelligent drives. 

2. Normally only two hard drives per chain supported. 

3. Only hard drives supported.(2) 

4. Newer IDE controllers support secondary data caches. 

5. Most IDE drives have a maximum capacity of 520MB.(3) 

6. Newer IDE hard drives generally support 256K caches.(4) 

7. IDE generally has lower data transfer rates than SCSI.(5) 

8. IDE hard drives are less expensive, and in much greater use. 

Legend: 

(1) This support is present in most SCSI-2 compliant controllers and hard 
drives. This technique allows requests to be handled by the drives, to 
allow it to honor those requests where the heads on the drives may be 
closest, and also allow to have multiple requests pending on the drive 
rather than in the system. 

(2) A proposal for IDE interface CD-ROM drives was recently adopted by 
several leading manufacturers. It is expected that IDE interface CD- 
ROM drives should become available by the end of 1994. 
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(3) A group of manufacturers adopted a new standard for IDE hard drives. 
Recently IDE hard drives have become available in capacities as high as 
1+ gigabytes. 

(4) Original IDE based hard drives came with little or no caches built-in. 
Most IDE hard drives available after 1992, generally have some sizable 
caches built in. 

(5) Original IDE drives were, because of ties to older hardware designs, 
were considerably slower than their SCSI counterparts, newer drives 
based on design enhancements, have data throughput rates approaching 
those of SCSI. 


Polling vs. Interrupt driven Secondary Storage Device Drivers 

SCSI devices are typically interrupt driven, while IDE devices typically use a 
polling method to transfer data. The polling method is not as efficient for 
multi-tasking operating systems like OS/2 because the device driver for the 
most part will keep the CPU busy polling the device to detect the end of the 
data transfer. This does not allow other processes or threads to run, while the 
data transfer is occurring. With interrupt driven devices, other processes and 
threads can run in the background while a data transfer is occurring. This is 
much more efficient. 

Even though polling is less efficient, this polling mechanism can have a 
great effect on the play back of movies. The key is the size of the data transfers 
that are requested. Large data transfers will cause the play back of video to be 
jerky because the video display threads will not get control of the CPU to run 
during a data transfer. This causes the video frames to be displayed less fre¬ 
quently, causing a jerky motion. It is recommended that small read requests be 
employed when playing movies. 

The streaming subsystem within MMPM/2 uses a dynamically adjustable 
method of reading data from secondary storage. It provides a performance 
enhancement for hard drives and CD-ROM devices that have device drivers 
that poll during data transfer. This causes the CPU to be directly involved in 
the data transfer for the length of the data transfer. The solution to the prob¬ 
lem is for the streaming system to adjust the reads to smaller sizes and to yield 
the CPU in between each read. This improves digital video playback. The 
yielding is dynamically adjusted depending on how much data is available in 
the audio and video streams. The streams represent a sequence of buffers that 
have been read from a file and parsed into audio and video data and is avail¬ 
able to the video display engine and audio hardware. If the buffers are mostly 
full, then the yields remain at 100 ms. If the buffers are mostly empty, the 
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yielding can range from no yield to 100 ms. The yield is pro-rated to the num¬ 
ber of full buffers. This will compensate for very high through-put movies that 
tend to want to display the data faster then it can be read, causing the data 
buffers to be mostly empty. 

Typically, this problem would cause the video to be displayed in a very errat¬ 
ic and jerky motion. This happens when the synchronization mechanisms try 
to compensate for being out of sync with audio. The default buffer read size is 
32kb and the starting yield value is 100 ms. This small buffer read mechanism 
with yields will tend to limit the maximum through-put possible from a system 
that does not have the polling problem and is less efficient than larger reads. 
MMPM/2 does provide a mechanism to change the default buffer size and yield 
time or to turn off this mechanism entirely. 

There are two environment variables that can be set before running a multi- 
media application. Each time a movie is loaded and the system is setup to play 
the movie (cue or play), these environmental variables are checked and the 
new values used. 

1. MMBUF: This sets the read buffer size. The default for movies is 32KB. 
To maximize the data transfer, change the buffer size to a larger value. 

2. MMYIELD: This sets the yielding time. The default is initially 100 ms 
and it is dynamically adjusted by MMPM/2. To disable it, set it to a value 
of -1, will cause no yields to occur. The maximum yield is 1 second. 

CD-ROMs 

Most newer CD-ROMs commercially available today are of the dual-speed, or 
double-spin variety. These drives have a data transfer rate of approximately 
300KB/second. There are a few manufacturers the have triple (450 KB/second), 
or quad (600KB/second), spin drives. These drives will generally cost $150 to 
$200 more than the dual-spin variety. Although there are still some of the orig¬ 
inal style (single-spin) drives available, investing in such hardware would not 
be a wise. As the use of multimedia becomes more widespread, more and more 
software taking advantage of the higher data capacity drives will be developed. 

Some CD-ROM drives are available using proprietary interfaces for a partic¬ 
ular sound card. If you choose sound card of this type, keep in mind that most 
of these cards will employ a non interrupt-driven, or polled interface, which 
will result in lower data throughput rates. Selecting a card equipped with a 
SCSI interface could be a wiser investment. 
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Sample Application 


INTRODUCTION 


In this chapter we will discuss various steps and components for putting 
together a multimedia based application. Our example is a OS/2 PM applica¬ 
tion written in the “C” language which utilizes MMPM/2 constructs and con¬ 
trols. The sample application we have provided, is both a programming exam¬ 
ple and a tool. It shows a developer several multimedia programming concepts, 
and allows a user to interact with some of the multimedia devices and content 
types supported by MMPM/2, from one place. Our application, PlayRec 
(. PlayRec.EXE ), supports two modes of operation, a PLAYER mode, and a 
RECORDER mode. There are two menus which are supplied for loading, and 
saving files, changing the recording settings, and querying information about 
the files or data buffers currently in use by the application. Before we go into 
how the application was written, let us look at what features are available 
within the sample, and how to use them. 

Using the Sample Application 

The RECORDER mode will allow the user to record waveaudio data in PCM 
format. The user may load, save, and clear out (New menu option) any files or 
data which may be loaded or recorded with some restrictions. “Saving” is only 
supported under RECORD mode. Modifying the sampling rate, bits per sam¬ 
ple, etc. of a waveaudio file that has been loaded, when the application is also 
unsupported. Once the user has recorded what they wish, there are two menu 
options, Save and Save As, which can be used to save the audio out to disk. 
The user can also select NEW to reset the RECORDER. To see what the 
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options can be set for RECORDER mode look like, refer to the bitmap in 
Figure 11-4. which is the settings menu. The settings menu allows for modifi¬ 
cation of any or all of the recording options. The Input menu item allows the 
user to specify whether the source for audio will be a microphone or line input. 
The RECORDER will adapt it is settings menu (bits per sample, samples per 
second, etc.) according to the capabilities provided by the audio hardware on 
the system the application is run on. For instance, if you have a Soundblaster 
Pro®, you will be able to record in 8-bits per sample, but not 16. PlayRec will 
automatically enable or disable menu options based on user selections based on 
this concept. Taking the example of a Soundblaster Pro again, the menu item 
for selecting a bits per sample of 16 will be totally disabled, and non-selectable. 

The samples’ PLAYER mode allows the user to load and play waveaudio, 
MIDI or SMV (movie) file. If the user loads a new file, while the user is in 
record mode, the user will be prompted to either return and save the recorded 
audio to a file or to proceed to select a new file to load. The user can select the 
New option when PlayRec is in PLAYER mode, however, if the user does so, 
not only will the file that is currently loaded be discarded, but PlayRec will be 
set into RECORDER mode. The Info menu option will display a dialog that 
will tell the user the current mode (player or recorder), and any pertinent 
information regarding the data file or recorded audio which is currently in use 
by the application. The New, Open, Save, Save As, and Info menu options 
belong to the file menu, this menu is illustrated by the bitmap in Figure 11-5. 


COMPONENTS FOR MULTIMEDIA DEVELOPMENT 


Before putting together, or building an application, a developer must decide 
what function is going to be provided to the user, what utility or use this will 
give the user, and how to present the application. What type of resources will 
be required for building the application, as well as what tools to use to develop, 
or write, the application have to be chosen. The design must achieve whatever 
function was intended that the application must provide. We will look at some 
aspects of each of these issues in the following sections. We will also provide 
pieces of the sample application to help explain the process of putting together 
a multimedia enabled application from start to finish. 

Look and Feel and Program Design 

To design a good application you must take into consideration the way the 
application appears to the user; is it easy to use, and it does appear appealing 
enough to make the user want to continue using it. As a developer, the deci- 
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sions you make about look and feel will directly affect not only how the applica¬ 
tion is perceived by the user, but in many ways how the program will itself 
work, and how it will have to be implemented. 



Figure 11-1. Sample application—PlayRec (Player / Recorder) 

Figure 11-1 represents our sample application, PlayRec , which is the play¬ 
er/recorder we discussed in the chapters’ introduction. Before a single line of 
code is written in any development project, an idea of the function or purpose 
the application will serve; the look is best lain out plainly, and the functionali¬ 
ty necessary, enumerated or outlined. If there is a certain layout for the visual 
aspects of the application desired, simple paper sketches will serve you well in 
creating the look and feel of the application. The look and feel design dictate 
the way the application is designed internally and is implemented because the 
pieces have to not only appeal visually to the user, they must inter-relate 
cooperatively. 

Controls and Resources 

When designing an OS/2 PM application, invariably, you will use resources 
such as dialogs, menus, buttons, bitmaps, etc. Just as in the design of the over¬ 
all application look and feel was of great importance, the same is true here. For 
instance, if you wish to have a graphic button with a particular look, you might 
utilize, as we did for the record button (the one with microphone bitmap, if you 
hadn’t guessed), the icon editor, or some other drawing package to create a cus¬ 
tom bitmap to use. To develop the overall layout of a particular dialog or other 
resource, you might choose to use the dialog editor or a case design package 
such as Prominare Designer. 


Dialogs 


Once we had a good idea of what function we wanted to provide for the sample 
application, Designer was used to visually lay out what the dialog should look 
like. We used three graphic buttons, a circular slider, and a standard PM slider 
control. Once the resources were laid out the way we wanted them, the follow¬ 
ing resource file was then generated to serve as a template for the dialog itself. 
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#define INCL_WINSYS 

//define INCL_WINSTDDLGS 

//define INCL_WINSTDSPIN 
#define INCL_NLS 
#define INCL_SW 

//include <os2.h> 

#include <os2me.h> 

//include “mpplay.h" 

BITMAP IDBMP_PLAY LOADONCALL FIXED .\PLAY.BMP 

BITMAP IDBMP_RECORD LOADONCALL FIXED .\RECORD.BMP 

BITMAP IDBMP_ST0P1LOADONCALL FIXED .\ST0P1.BMP 

BITMAP IDBMP_STOP2LOADONCALL FIXED .\ST0P2.BMP 

BITMAP IDBMP_MINUSLOADONCALL FIXED .\MINUS.BMP 

BITMAP IDBMP_PLUS LOADONCALL FIXED .\PLUS.BMP 

DLGTEMPLATE DLG_PLAYREC 850 LOADONCALL MOVEABLE DISCARDABLE 

BEGIN 

DIALOG “PlayRec”, DLG_PLAYREC, 144, 134, 252, 30, FS_NOBYTEALIGN | 

WS CLIPSIBLINGS | WS_SAVEBITS | WS_VISIBLE, FCF SIZEBORDER | 

FCF_TITLEBAR | FCF_SYSMENU | FCF_MINBUTTON | FCF_AUT0IC0N | 

FCF_TASKLIST 

BEGIN 

CONTROL “StopPause”, GRB_STOPPAUSE, 2, 3, 26, 19, 

WC_GRAPHICBUTTON, GBS_TWOSTATE | 
WS_TABSTOP | WS_VISIBLE 
CTLDATA GB_RESOURCE, 2, 803, 804, 0 

CONTROL “Play”, GRB_PLAY, 37, 3, 26, 19, 

WC_GRAPHICBUTTON, GBS_ANIMATION | 

WS_TABSTOP | WS_VISIBLE 

CTLDATA GB_RESOURCE, 1, 801, 0 

CONTROL “Record”, GRB_RECORD, 73, 3, 26, 19, 

WC_GRAPHICBUTTON, GBS_TWOSTATE | 

WS_TABSTOP | WS_VISIBLE 

CTLDATA GB_RESOURCE, “”, 1, 802, 0 
CONTROL"”, CSLD_VOLUME, 111 0, 32, 26, 

WC_CIRCULARSLIDER, CSS_POINTSELECT 
CSS_PR0P0RTI0NALTICKS | WS_VISIBLE | 

C S S_MID POI NT 

CONTROL"”, DDLG_SLIDER, 148, 3, 100, 20,WC_SLIDER, 

SLS_HORIZONTAL | SLS_CENTER | 
SLS_BUTTONSLEFT | SLS_HOMELEFT | 
SLS_SNAPTOINCREMENT | 

SLS_RIBBONSTRIP | SLS_PRIMARYSCALE1 

WS_TABSTOP | WS_VISIBLE 

CTLDATA 12, 0, 10, 10, 10, 10 
END 
END 

Figure 11-2. Dialog template definition, playrec.rc 
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The dialog template illustrates each resource required to present the visual 
image which is in Figure 1-1. Visually, an application prototype may appear 
the way you wish it to on one system; however, different display resolutions 
cause assumptions made about object placement to be a major factor to con¬ 
tend with. Look at the CONTROL statements for the STOPPAUSE, PLAY, 
and RECORD buttons. We laid out these three buttons to be have the left 
edge of one button to be 10 pixels to the right of the right edge of the button 
immediately to the left of it. The reason that was done was so that the buttons 
would not only appear equidistant from each other, but so that they would not 
overlap on different display resolutions (1024*768 vs. 640*480). Again, another 
instance where look and feel dictates how you go about the development 
process. 


Menus 


Even though there are graphical buttons and sliders to allow the user to 
manipulate a multimedia content file (waveaudio, MIDI, or SMV), there need¬ 
ed to be a way that the user could specify what files or data to operate on. 
Obviously, we need a menu (or menus) of some sort. 

To make the application a little unique, we opted to forego the standard 
menu bar arrangement used by most applications, and use popup menus 
instead. The resource templates for popup menus are identical to “standard” 
menus. Again, we used Designer to visually create the menus as we would have 
them appear. Following is the output which would be the basis for our menu- 
ing within the application: 


ICON WIN_SAMPLE LOADONCALL FIXED .\PLAYREC.ICO 

MENU menu_Record 850 MOVEABLE DISCARDABLE 
BEGIN 

SUBMENU “-Samples per Sec” 

BEGIN 

MENUITEM “8Khz”, 

MENUITEM “llKhz”, 

MENUITEM “22Khz”, 

MENUITEM “44.lKhz”, 

END 

SUBMENU “-Bits per Sample”, IDM_BITSPERSAMPLE, MIS_TEXT 

BEGIN 

MENUITEM “8—bit”, IDM_BIT8, MIS_TEXT 

MENUITEM “16-b-it”, IDM_BIT16, MIS_TEXT 

END 


IDM_SAMPLESPERSEC, MIS_TEXT 

IDM_KHZ8, MIS_TEXT 
IDM_KHZ11, MIS_TEXT 
IDM_KHZ22, MIS_TEXT 
IDM_KHZ44, MIS_TEXT 
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SUBMENU “-Channels”, 

BEGIN 

MENUITEM “-Mono”, 
MENUITEM “-Stereo”, 

END 

SUBMENU “-Input”, 

BEGIN 

MENUITEM “-Microphone”, 
MENUITEM “-Line-in”, 

END 

END 


IDM_CHANNELS, MIS_TEXT 

IDM_M0N0, MIS_TEXT 
IDM_STEREO, MIS_TEXT 

IDM_INPUT, MIS_TEXT 

I DM_MICROPHONE, MIS_TEXT 

IDM_LIN EIN, MIS_TEXT 


MENU menu_ST0P 850 MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM “-New”, IDM_NEW, MIS_TEXT 

MENUITEM “-Open”, IDM_0PEN, MIS_TEXT 

MENUITEM SEPARATOR 

MENUITEM “-Save”, IDM_SAVE, MIS_TEXT 

MENUITEM “S-ave as...”, IDM_SAVEAS, MIS_TEXT 

MENUITEM SEPARATOR 

MENUITEM “-Info”, IDM_INFO, MIS_TEXT 


END 


Figure 11-3. Menu template resource definitions, mpplay.rc 

What we created are two separate menu structures where one would be used 
for the STOPPAUSE button (File menu) and the other could be used for the 
RECORD (Settings menu) button. The menu_STOP menu (Figure 11-3) was 
designed to provide access to things such as the standard file dialogs for saving 
away a set of data to a file (waveaudio recording only). Also, if you are finished 
working with one particular set of data, to create a context for a new one from 
scratch, or load in a new from disk, we provided a New and an Open for per¬ 
forming either of these options. The Info menu option was provided to allow 
the application to tell the user some information about the file or data that is 
currently in use. The menu_RECORD (see Figure 11-4) menu provides 
options for setting most of the options types supported by the waveaudio 
device. The options are used for setting up the waveaudio device into the prop¬ 
er mode, before recording. PlayRec only supports PCM recording specifically, 
on purpose. Support for ADPCM format recording could be added to the menu 
by simply creating a new submenu in the template and adding in menu-items 
for each compression format desired. Obviously, there would have to be code to 
support setting the correct format tag mode. Refer to Chapter 5, under the 
Setting Device Controls and Attributes section for more information about the 
format tag modes. 
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Samples per Sec 4 
Bits per Sample 4 
Channels 4 

input 4 

"TSfigl 


8Khz t 
11 Khz 
22Khz 
Ml Khz 


BHBn 


Figure 11-4. “Settings” menu design and layout for PlayRec 



Figure 11-5. “File” menu design and layout for PlayRec 


Assigning Resource ID's 

The way OS/2 PM handles all of its resources is via a mechanism of associating 
an ID per resource. For each resource object within an application, there will 
be one specific number to signify which object, any given object is. An object in 
our case is a bitmap, graphic button, or any uniquely distinct resource which 
will be used by OS/2 PM (or MMPM/2). The list of unique identifiers can be 
housed in one globally referenced header file which can be included by all 
source code modules and resource templates. 


/* DEFINITIONS FOR BUTTONS and their associated bitmaps */ 


/* */ 

#define 

DFG_PFAYREC 

500 

#define 

GRB_STOPPAUSE 501 


#define 

GRB_PFAY 

502 

#define 

GRB_RECORD 

503 

#def ine 

CSLD_V0LUME 

504 

#define 

DDLG_SLIDER 

505 
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#define 

I DBM P_P LAY 


801 

#define 

IDBMP_RECORD 

802 


#define 

IDBMP_ST0P1 


803 

#define 

IDBMP_ST0P2 


804 


/* DEFINITIONS 

, FOR MENUS and 

thei r 

submen 

/* */ 




#define 

menu_Record 


805 

#define 

IDM_SAMPLESPERSEC 806 


#define 

IDM_KHZ8 


816 

#define 

I DM_KH Z11 


817 

#define 

IDM_KHZ22 


818 

#def ine 

IDM_KHZ44 


819 

#define 

IDM_BITSPERSAMPLE 807 


#define 

IDM_BIT8 


814 

#define 

I DM_BIT16 


815 

#define 

IDM_CHANNELS 

808 


#define 

IDM_M0N0 


812 

#define 

o 

1 

CO 
—1 
m 
yo 
m 
O 


813 

#define 

IDM_INPUT 


809 

#define 

ID M_MICR0PH0NE 

810 


#define 

ID M_ LIN EIN 


811 

#define 

menu_ST0P 


607 

#define 

IDM_NEW 

701 


#define 

I DM_0 PEN 


702 

#define 

I DM_S E P1 


703 

#define 

IDM_SAVE 


704 

#define 

IDM_SAVEAS 


705 

#define 

IDM_SEP2 


706 

#def ine 

I DM_IN F0 


707 


Figure 11-6. Resource ID definitions, mpplay.h 

Notice that all the resources in Figure 11-6 are logically grouped and 
arranged. The resource values for the menus and their submenu items aren’t 
in sequential order. This is because when building the menus visually with 
Designer , the top layer menu structure was defined first, then the individual 
submenu items defined afterwards. Numbering resource IDs in a specific or 
sequential order is not absolutely necessary. Here are two simple rules which 
will make the process of assigning resource IDs values easier: 

1. When defining separate hierarchical resource structures, such as 
separate menus, or dialogs, provide an adequate space of value 
open between the base values assigned to the top level structures. 
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2. When defining a resource structure (such as a menu hierarchy), 
apply rule number 1 (above) to provide adequate number spacing 
to accommodate any additions which may become necessary. 

This method for assigning resource IDs is rather straightforward, and in a 
nutshell simply means “group things logically, and leave yourself enough 
breathing room.” We have now covered the parts of creating and organizing the 
visual components to our application, the window dressing. The next step in 
the process is to build the foundation for the application, and its support 
structure. 

Coding Your Application 

Once you have developed a good idea of how your application will behave and 
what it will look like, the process of actually writing the application will proba¬ 
bly be where the majority of your effort will be focused. Where to lay compo¬ 
nents of your application across one or more source code files, how to tie the 
different parts back together, and make them work cooperatively is essential. 
The code for the application and all the necessary resource components are 
provided on the diskette included with the book. We discuss sections of code for 
the sample application, rather than the entire thing, what the purpose each 
function serves how to it is used accomplish its purpose. Our primary goal is 
not to present you with any programming philosophy. Instead, we present 
practical hints, tips and information about how to develop multimedia enabled 
applications in a way which will make the development process more 
productive. 

User Interface 

Although MMPM/2 is short for Multimedia Presentation Manager/2, not all 
MMPM/2 applications need be based on PM. However, our sample is. We have 
to deal with PM and its interface, but we will not go into any specific detail on 
the PM APIs. When an MMPM/2 user interface (for instance, 
WinRegisterSecondaryWindow ) function is used in the sample, we will dis¬ 
cuss what its purpose is. PM-based applications are built on the concept of win¬ 
dowing, and messaging. Any graphic button, secondary window, or MMPM/2 
control will require at least some of PM’s windowing and graphics support. 
Following is one instance where we must deal with PM to set up our running 
environment, and establish our connection (the windows) with the user. 
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/* 

Provide appropriate 
//define INCL_ & //include’s 

*/ 

//pragma title(“Program Name -PlayRec- Version 0.1 (MPPlay.C)”) 
//pragma subtitle(“ Module Purpose - Interface Definitions”) 

//define INCL_D0S /* Include OS/2 DOS Kernel */ 

//define INCL_WIN /* Include OS/2 PM Windows Interface */ 

//define INCL_0S2MM 

//define I NC L_S ECON DARYWINDOW 

//define I NC L_C IRCU LARS LID E R 

//define I NC L_GRAPH ICBUTTON 

//define INCL_WINSTDSLIDER 

//define INCL_WINSTDFILE 

//define INCL_WINSTDDLGS 

//include <os2.h> 

//include <os2me.h> 

//include <sw.h> 


//include “appdefs.h 
//include “mpplay.h” 


/* 

Fi1ename: 

MPPlay.C 

*/ 

/* 

Version: 

0.1 

*/ 

/* 

Created: 

1994-07-28 

*/ 

/* 

Revised: 

1994-08-30 

*/ 

/* 



- */ 


static HMODULE hmod; /* DLL Module Handle */ 

PSZ pszMPPlayClassName = (PSZ)”MPP1ay”; 


int main ( int argc, char *argv[] ) 

{ 

hAB = Winlnitialize(OUL); 

hmqMPPlay = WinCreateMsgQueue(hAB, OL); 


/* 

Any other application specific initialization, such as global 
variables, etc. should be set up here. 

*/ 


Figure 11-7. Application Registering (MMPM/2) and Initialization, mpplay.c 
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WinRegisterCircularSlider(); 
hwndMPPlayFrame = 


WinLoadSecondaryWindow(HWND_DESKTOP, 

/* 

dialog 

box.parent 

*/ 

HWNDJDESKTOP, 

/* 

dialog 

box.owner 

*/ 

(PFNWP) PlayRecD' 

IgProc, /* 

‘Window’ Proc 

*/ 

(HMODULE) NULL, 

/* 

Where 

is the dialog, 

.*/ 

DLG_PLAYREC, 

/* 

Dialog 

ID. 

*/ 

(PVOID) NULL); 

/* 

Creatii 

on Parms 

*/ 

Retrieve the handle to the dialog box by 

specifying 

the QS_ 

.DIALOG 



flag.*/ 

hwndMPPlay = WinQuerySecondaryHWND(hwndMPPlayFrame, QS_DIALOG); 


/* 

Add Default Size menu item to system menu of the secondary window. 

*/ 


WinInsertDefaultSize(hwndMPPlayFrame, (PSZ)”Default Size”); 


/* Get and dispatch the message to program */ 

/* window */ 

while ( WinGetMsg(hAB, &qmsg, (HWND)NULL, OUL, OUL) ) 
WinDispatchMsgChAB, &qmsg); 


/* Have received a WM_QUIT, start the program */ 

/* shutdown by destroying the program windows */ 

/* and destroying the message queue */ 

WinDestroySecondaryWindow(hwndMPPlayFrame); 

WinDestroyMsgQueue(hmqMPPlay); 

/* Relinquish any system resources (memory, semaphores, etc.) 
we may have allocated initially 

*/ 

/* Notify PM that main program thread not needed */ 

/* any longer */ 

WinTerminate(hAB); 

/* Exit back to OS/2 cleanly */ 
return(O); 

} 


Figure 11-7. Application Registering (MMPM/2) and Initialization , mpplay.c 
(Continued) 
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Figure 11-7, presents a simplified view of the initialization process of our 
application. The calls to WinRegisterSecondaryWindow and 
WinLoadSecondaryWindow are necessary to initialize the secondary win¬ 
dow support in MMPM/2, and to retrieve the dialog template (see Figure 11-2) 
we defined for our application. When the secondary window is being created, 
there is a sequence of messages that are sent directly to it’s window procedure 
(' WM_INITDLG , etc.) so that the application has the opportunity to perform 
any sort of application specific initialization. Every window created under PM 
has at least one window procedure. A window procedure is a function which is 
the recipient of messages, or events, from PM or other windows. These mes¬ 
sages commonly relate to some activity or interaction with the user or some 
other window. Once the secondary window is created, and initialized, control 
for the application will flow solely through the WinGetMsg/WinDispatchMsg 
loop until the application is exited by the user. When the user exits the appli¬ 
cation, the WinDestroySecondaryWindow API will deallocate any resources 
that were reserved for our window, and then return them back to the system 
for reuse. 


#define MWM_INITCTLS WM_USER+1000 


case WM_INITDLG: 

WinPostMsg( hWnd, MWM_INITCTLS, 0, 0 ); 
break; 

case MWM_INITCTLS: 

WinSendMsg( WinWindowFromID( hWnd, DDLG_SLIDER ), 
SLM_SETTICKSIZE, 

MPFR0M2SHORT(SMA_SETALLTICKS,5L), 

0L 

); 

/* Subclass the two buttons (STOP, and RECORD) */ 
pDefaultStopButtonProc = 

WinSubclassWindow( WinWindowFromID(hWnd,GRB_ST0PPAUSE), 
StopButtonSubclassProc ); 


pDefaultRecordButtonProc = 

WinSubclassWindow( WinWindowFromlDChWnd,GRB_REC0RD), 
RecordButtonSubclassProc ); 


Figure 11-8. Handling window / dialog specific initialization, prdlg. 
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return ((MRESULT)O); 
break; 

./* Any other application specific code */ 

case WM_CL0SE : 

/* 

Restore our subclassing 

*/ 

WinSubclassWindow( WinWindowFromlDChWnd, GRB_STOPPAUSE), 
pDefaultStopButtonProc ); 

WinSubclassWindow( WinWindowFromID(hWnd, GRB_RECORD), 
pDefaultRecordButtonProc ); 

return(WinDefSecondaryWindowProc(hWnd, msg.mpl, mp2)); 
break; 


Figure 11-8. Handling window I dialog specific initialization, prdlg.c 
(Continued) 

Figure 11-8, represents how we set up our secondary window to support the 
popup menus, as well as setting the scaling markers on our slider control. We 
subclass the graphic buttons so that we could to take advantage of the fact that 
the standard window class for graphic buttons did not employ the use of the 
right mouse button (the same mechanism used by containers in the Workplace 
Shell® to display context menus). Clicking the right mouse button once causes 
the appropriate menu pop up into view. Also, note the WM_CLOSE processing 
in the code. When the user exits, or closes, the application, it is always a good 
practice to restore the default window procedure setting for anything that is 
been subclassed. For further reference on secondary windows and their support 
under MMPM/2, refer to Chapter 9, Multimedia Secondary Windows and 
Controls, or to Appendix D. 

Multimedia Support 

Many books on the subject of software development make a point to mention 
that separating the “main” program code from the code that interacts with the 
user (the UI) is essential for good program design. The same fundamental rule 
would apply in the case of code that interacts with MMPM/2. The program code 
that calls directly into MMPM/2 is provided as set of ancillary functions which 
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are in module mciapi.c. Although there will be places in an application where 
some degree of interaction with MMPM/2 will take place (see Figure 11-9), the 
remainder of the application will use the functions in mciapi.c to handle most 
tasks which require interaction with the MCI for us. 


case MM_MCINOTIFY: 


usNotify = SH0RT1FROMMP(mpl); 
usUser = SH0RT2FR0MMP(mp2); 
usDevicelD = SH0RTlFR0MMP(mp2); 
usMessagelD = SFI0RT2FR0MMP(mp2); 


/* SUCCESS ? */ 

/* Retrieve user parm */ 
/* Which device ID? */ 

/* MM_MCINOTIFY) */ 


if ( usNotify == MCI_N0TIFY_ABORTED ) 

/* Process the event */ 


ulRC = mciGetLastError( (ULONG)usNotify, 

(PSZ)szErrorBuf, 
MAX_ERROR_LEN ); 


/* 

Flandle Error accordingly 
Clean-up etc. 

*/ 


return( (MRESULT)O); 

break; 

case MM_MCICUEPOINT: 

usCuelD = SH0RT1FROMMP(mpl); /* ID key for this event */ 

usDevicelD = SH0RT2FR0MMP(mpl); /* Which device ID ? */ 

usMSeconds = MSECFR0MM(mp2); /* Convert MMTIME to 

milliseconds */ 

/* Process CUEPOINT event */ 
return( (MRESULT)O); 
break; 

case MM_MCIPOSITIONCHANGE: 

usPositionID = SHORTlFROMMP(mpl); /* ID key for this event */ 
usDevicelD = SH0RT2FR0MMP(mpl); /* Which device ID? */ 

usMSeconds = MSECFR0MM(mp2); /* Convert MMTIME to 

Figure 11-9. Simplified event notification and handling, prdlg.c 
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milliseconds */ 


/* Process the POSITION event */ 
return( (MRESULT)O); 

break; 


Figure 11-9. Simplified event notification and handling, prdlg.c 

This type of notification handling could be encapsulated within another 
function. Since this interaction primarily deals with notifications, it makes 
more sense in our example to incorporate it into the rest of the code within the 
window procedure for the dialog. Support for these events assumes that when 
calling into the MCI, the NOTIFY keyword was explicitly specified in the com¬ 
mands sent to it. 

Interfacing with MMPM/2 

Although the last section presented how the main application code will, to 
some extent, interface with MMPM/2, the majority of the application will uti¬ 
lize the ancillary, or helper, functions to perform this task. 


//pragma title(“Program Name - MPPLAY Version 0.00.01 (mciapi.C)”) 


//pragma 

subtitle(“Module Purpose 

- MMPM/2 Interface 

Definitions”) 


//define 

IN C L_WIN 

/* 

Include 

OS/2 PM Windows Interface 

*/ 

//def ine 

INC L_G PI 






//def ine 

INC L_SW 

/* 

Include 

OS/2 MMPM/2 

Interface 

*/ 

//def ine 

INC L_M M10 0 S 2 

/* 

“ 

” MMIO 

“ 

*/ 

//def ine 

INCL_0S2MM 






//define 

INCL_SECONDARYWINDOW 






//define 

INC L_CIRCU LARS LID E R 






//define 

INCL_GRAPHICBUTTON 






//define 

INC L_WINSTDSLIDER 






//define 

INC L_WIN S T D FILE 






//define 

INC L_WINSTDDLGS 






#include 

<stdio.h> 

/* 

Include 

“C” runtime 

support 

*/ 

#include 

< s td1ib.h> 

/* 




*/ 


//include <os2.h> 

/* Include OS/2 PM datatypes and API 

*/ 


/* definitions 

*/ 


Figure 11-10. #define and #include definitions , mciapi.c 
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//include <os2me.h> /* Include datatypes & API definitions*/ 


#include <sw.h> /* for MMPM/2 support */ 

//include “appdefs.h” /* Include our application specific */ 

/* Datatypes and variables */ 

//include “mpplay.h” /* Include Resource ID definitions */ 


Figure 11-10. #define and #include definitions, mciapi.c (Continued) 

The set of #cLefine’s and #include’s in Figure 11-10 are common to all the 
examples provided for the multimedia support section. They represent control 
information used by the compiler when an application is built to control which 
datatypes, constants, and API definitions which may be used and or referenced 
by the code that follows. 

The code examples extracted from the MMPM/2 interface support module, 
mciapi.c, present only a subset of the total number of functions that are pro¬ 
vided. Before each function declaration there is a comment which describes in 
general what service the function provides. 


/* Open the target device specified by the alias and data element 
Data element will cause an implicit determination of the 
device type. The application can then query the DEVICE_TYPE 
via a “capability ALIAS device type” 

*/ 


ULONG OpenDevice( 
{ 


PSZ pszElement, PSZ pszDeviceAlias, 
HWND hWndNotify ) 


PSZ pszReturn, 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Open”: 

“open DataElement alias DeviceAlias <wait|notify>” 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “open %s alias %s %s”, 

pszElement, 
pszDeviceAlias, 

( !hWndNotify ) ? “wait” : “notify 

); 


Figure 11-11. OpenDevice—Opens a multimedia device and loads a data 
element into it, mciapi.c 
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ulRC = mciSendString( szTemplate, pReturn, iLen, 

(!hWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 


return( ulRC ); 

} 


Figure 11-11. OpenDevice—Opens a multmedia device and loads a data 
element into it, mciapi.c (Continued) 

We provide the ability in all our functions for the caller to implicitly specify 
notification to the caller by passing in a window handle as an argument. 
Although the examples do not perform explicit verification that the window 
handle is valid, it is a wise step to take, and it can be performed by a simple 
call to the WinlsWindowO PM API, in place of our ‘X!hWndNotify)?...etc.’’ 
code. 

Most of the functions’ code falls into three steps: parameter verification, 
command construction, and the call into the MCI. Let us look at each of these 
step in a little detail before we discuss what each function specifically does. At 
the beginning of each function, we always verify if we were provided a buffer in 
which to return any data to the caller. Since mciSendString allows provides 
this as its mechanism in which to return resultant information for all requests, 
in some cases, especially when querying a mode setting, or device setting it’s 
wise to provide a buffer for return information. 

The next step is build the command string. Each sprintf call has a template 
string from which the command is built from. For instance, in the 
OpenDevice function (Figure 11-11); our function performs an open on a 
device in a way where, at the time we open the device, we may not even have 
an idea of what type of device the device is, and rely on the default filetype 
associations provided by MMPM/2 to determine which device to open. The 
return buffer is used to return a device ID for the device that was opened, 
which can be used later. 


/* 

Query the device type via the alias used on the OpenDevice Command 

*/ 


ULONG QueryDeviceType( PSZ pszAlias, PSZ pszReturnDeviceType, 
HWND hWndNotify ) 


ULONG ulRC=0L; 

Figure 11-12. QueryDeviceType—Retrieves the device type of a device alias, 
mciapi.c 
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CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn; 

if (*pszReturnDeviceType) 


pReturn = pszReturnDeviceType; 

/* 

Build the command string for iCapability device typei: 

1 capability DeviceAlias device type <wai11notify>i 

*/ 

pCommand = (PSZ)sprintf( szTemplate, 

“capability %s device type %s”, 
pszDeviceAlias, 

( IhWndNotify ) ? “wait” : “notify” 

); 


ulRC = mciSendString( szTemplate, pReturn, iLen, 
(IhWndNotify) ? (HWND)NULL 
: hWndNotify, 

0 ); 

} 

else return( ERR0R_INVALID_PARAMETER ); 
return( ulRC ); 


Figure 11-12. QueryDeviceType- Retrieves the device type of a device alias, 
mciapi.c (Continued) 

Once the device has been opened, a call to QueryDeviceType will return a 
string in pszReturn. The device type returned in the string is the predefined 
device type name for the type of device which the alias references. This infor¬ 
mation is necessary partially because of the way we performed the 
OpenDevice. If the device type for a particular data element was known in 
advance, then a modified version of the OpenDevice could be implemented 
easily to include the device type in the command string for the open command. 
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/* 

Attempts to identify the file type of the data element specified 

*/ 

ULONG IdentifyData( PSZ pszElement, PULONG pulDataType ) 

{ 

ULONG ill RC=0L; 

CHAR szTemplate[255]; 

MMFORMATINFO mmFmtlnfo; 

FOURCC fccStorage; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 

if (*pszElement) 

{ 

ill RC = mmioldentifyFi 1 e( pszElement, 

(PMMIOINFO)NULL, 

(PMMFORMATINFOl&mmFmtlnfo, 

(PFOURCC)&fccStorage, 

0L, 

0L ); 


if ( ! u 1 RC ) 

{ 

^pulDataType = mmFmtlnfo.ulMediaType; 

} 

} 

else returnC ERROR_INVALID_PARAMETER ); 
return( ulRC ); 

} 


Figure 11-13. IdentifyData—attempts to identify the media data type of a file, 
mciapi.c 

The IdentifyData function calls the MMPM/2 MMIO component to attempt 
to determine the media type (waveaudio, midi, smv) of a particular file. If 
PlayRec currently has a device of a different type than the one of the data ele¬ 
ment selected, the device that is open will be closed, and a new device instance 
created for the new data element. 
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/* 

Load a data element into a device instance that’s already open. 

*/ 

ULONG OpenData( PSZ pszElement, PSZ pszDeviceAlias, PSZ pszReturn, 
HWND hWndNotify ) 


ULONG ulRC=OL; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for iLoadi: 

“load DeviceAlias DataElement|new <wait|notify>” 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “load %s %s %s”, 

pszDeviceAlias, 

(*pszElement) ? pszElement : “new”, 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 


returnC ulRC ); 


Figure 11-14. OpenData—Loads a data element into an opened device, mciapi.c 

The OpenData function will take a data element and attempt to load it into 
a device alias which is already open. If the data element supplied is of a differ¬ 
ent type then that of the device which currently open, an error will be returned 
to the caller. At this point, we can call IdentifyData to determine the correct 
media type for the data element and proceed accordingly. If the data element is 
of the same format as the previous one, MMPM/2 will reuse as many buffers 
from the previous one, as possible for the new one. 
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/* 

Initiate playback of whatever 

*/ 

ULONG PlayDevice( PSZ pszDeviceAlias,PSZ pszFrom,PSZ pszTo, 
PSZ pszReturn, HWND hWndNotify) 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Play”: 

ipi ay DeviceAlias <from X> <to Y> <wai11notify>i 

Where, X = starting media position 
Y = ending media position 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “play %s %s %s %s %s %s”, 

pszDeviceAlias, 

(*pszFrom) ? “from” : “ “, 

(*pszFrom) ? pszFrom : “ 

(*pszTo) ? “to” : “ “, 

(*pszTo) ? pszTo : “ “, 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 

return( ulRC ); 

} 


Figure 11-15. PlayDevice—Plays back data element loaded for specified device 
alias, mciapi.c 

The PlayDevice function will play back whatever data element is currently 
loaded into the device specified by pszDeviceAlias. By specifying values in 
the pszFrom and pszTo parameters, it is possible to implicitly invoke the 
from and to keywords for the play command. The function assumes that a 
valid numeric value will be specified by the caller for these parameters. The 
sprintf function builds the command line completely. Please take note of the 
way we implemented the mechanism for implicitly specifying keywords and 
parameters. This mechanism is employed by several of the functions we pro- 
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vide. It is a simple method for implementing support for parameterization to 
MCI string commands. 


/* Perform an explicit mode switch ( PLAY or RECORD ) on a device 
alias ( supported only for Waveaudio by the sample ) 

*/ 

ULONG ResetDeviceModeC PSZ pszDeviceAlias,PSZ pszMode,PSZ pszReturn, 

HWND hWndNotify ) 


ULONG ulRC=0L; 

ULONG ulRet=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Set .... mode”: 

“set DeviceAlias <record|piay> <wait|notify>” 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “set %s mode %s %s”, 

pszDeviceAlias, 
pszMode, 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 

if (ulRC = MCIERR_SUCCESS ){ 

{ 

pCommand = (PSZ)sprintf( szTemplate, “load %s new wait”, 

pszDeviceAlias 

); 

ulRet = mciSendString( szTemplate, (PSZ)NULL , 

0, (HWND)NULL, 0 ); 

/* Handle WORKPATH FULL errors, see chapter 5 */ 


} 

return( ulRC ); 

} 


Figure 11-16. ResetDeviceMode—Changes the current operating mode (waveau¬ 
dio device only), mciapi.c 
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The ResetDeviceMode function is a quick path method for changing oper¬ 
ating modes of the waveaudio device. It is used to switch from playback to 
record mode immediately. This function causes the data element loaded in the 
waveaudio device to be flushed from memory and a new temporary data ele¬ 
ment to be created. If ulRet returns a MCIERR_OUT_OF_MEMORY return 
code, then we can reset the workpath (MSV_WORKPATH) that that MMPM/2. 
Refer to Chapter 5, Audio Playback and Record for more information. The rea¬ 
son we say quick path method, is that in most cases, the natural impulse might 
be to close the device and reopen it, which really isn’t necessary in this 
instance. 


/* 

Seek within the data to the media position specified 

*/ 

ULONG SeekToPosition( PSZ pszDeviceAlias, PSZ pTo, 

PSZ pszReturn, HWND hWndNotify ) 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 
char pPos[16]; 

if ( *pTo ) 


/* 

Build the command string for “Seek”: 

“seek DeviceAlias <to start|to end|to P0S> 

<wait|notify>” 

Where, POS = new media position 

*/ 

if (strcmp(pTo,“start”)) strcpy(pPos, “to start” ); 
else if (strcmp(pTo,“end”)) strcpy(pPos, “to end” ); 
else sprintf( pPos, “to %i”, pTo ); 

pCommand = (PSZ)sprintf( szTemplate, “seek %s %s %s”, 

pszDeviceAlias, 
pPos, 

(!hWndNotify) ? “wait” : “notify” 

); 


ulRC = mciSendString( szTemplate, pReturn, iLen, 

Figure 11-17. SeekToPositioin—set the media position to a specific point, 
mciapi.c 
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(IhWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 

} 

else return( ERROR_INVALID_PARAMETER ); 
return( ulRC ); 

} 


Figure 11-17. SeekToPosition—set the media position to a specific point, 
mciapi.c (Continued) 

If the user moves the slider, PlayRec receives notification of this change, 
and queries the specific position within the scale the slider was set to. At that 
moment we need to move the media position for the device to the position spec¬ 
ified by the slider. The format of the seek command is rather straightforward, 
however, by allowing the caller to specify the start and end keywords, the 
command will support all three forms of the command. The only keyword com¬ 
mand not supported is the to nearest set, which seeks to nearest I-frame posi¬ 
tion preceding the value specified in pTo. 

The sliders’ primary scale was set to allow a range of 100 “time points.” 
Therefore, its resolution will only be accurate within a range relative to the 
time length of the data present. For example, if a data element is loaded that 
contains 10 seconds (10000 milliseconds), our slider will only be accurate with¬ 
in 100 milliseconds of any given media position. This factor varies by data con¬ 
tent time length in the millisecond format. If a MIDI file contains 50 seconds of 
music, the slider will only be accurate to within 500 milliseconds (or one-half 
second). 


/* 

Record waveaudio for a specific length of time ( or NOT ! ) 

*/ 

ULONG RecordData( PSZ pszDeviceAlias, PULONG pul From, PULONG pulTo, 
BOOL bOverwrite, PSZ pszReturn, HWND hWndNotify ) 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 

int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 

char cFrom[10]; 

char cTo[10]; 

char *pFrom; 

char *pTo; 


Figure 11-18. RecordData—Record waveaudio, mciapi.c 
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/* 

Build the command string for “Record”: 

“record DeviceAlias <from X> <to Y> <overwrite> 
<wait|notify>” 


*/ 


Where, X = start position & 
Y = end position 


if (*pulFrom) 

pFrom = itoa( (int)(*pulFrom), cFrom, 10 ); 
else pFrom=(char *)NULL; 

if (*pulTo) 

pTo = itoa( (int)(*pulTo), cTo, 10 ); 
else pTo = (char *)NULL; 

pCommand = (PSZ)sprintf( szTemplate, 

“record %s %s %s Is Is 1s %s”, 
pszDeviceAlias , 

(*pFrom) ? “from” : “ “, 

(*pFrom) ? pFrom : “ “, 

(*pTo) ? “to” : “ “, 

(*pTo) ? pTo : “ 

( bOverwrite )? “overwrite” : “ ”, 

( IhWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? NULL : hWndNotify, 

0 ); 

return( ulRC ); 

} 


Figure 11-18. RecordData—Record waveaudio, mciapi.c (Continued) 

The record command is somewhat the most complex of the MCI support 
functions provided because of the combinations of commands it can support: 

1. from, but not to; 

2. from and to; 

3. not from, but to; 

4. neither from or to. 

as well as the overwrite keyword. If a NULL is specified in either the 
pulFrom or pulTo parameters, then it is assumed that the associated key- 
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word is unnecessary to the string. In each of our functions we have checked for 
certain parameters to be present in some form of another to help dictate how to 
“build” the command string. The MCI parser follows along the same concept we 
have been applying here, but in reverse. When the MCI parser scans through a 
command string, it “unbuilds” a command to its basic components before pass¬ 
ing the command (or several commands) to the media driver. 


/* 

Save the current recording buffers out to a file 

*/ 

ULONG SaveFile( PSZ DeviceAlias, PSZ pszDataElement , 

PSZ pszReturn, HWND hWndNotify ) 

{ 

ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Save”: 

isave DeviceAlias Da ta Element <wai11notify>i 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “save %s %s %s %s”, 

pszDeviceAlias, 
pszDataElement, 

( !hWndNotify ) ? “wait” : “notify 
); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(!hWndNotify) ? NULL : hWndNotify, 

0 ); 


return( ulRC ); 

} 


Figure 11-19. SaveFile—Save record buffers to a file on disk, mciapi.c 

The save command demonstrated in the SaveFile function will have the 
MCI save away all recorded audio buffers out to the file specified in 

pszDataElement. 

In multitasking operating system environment, applications should be 
aware and account for other applications which may be running on the system. 
This point is especially important multimedia enabled applications, and in spe¬ 
cific, the subject of managing the device resources present in the system. This 
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means using good judgment in designing an application to allow MMPM/2 to 
manage devices. The issue of device ownership is discussed in the Resource 
Management section of Chapter 3. Look briefly at the two primary functions 
necessary for sharing a device under MMPM/2. 


/* 

Acquire ownership of an instance of the specified device alias 

*/ 

ULONG AcquireDevice( PSZ pszDevice, PSZ pszOwnership, PSZ pszReturn, 
HWND hWndNotify ) 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Acquire”: 

“acquire DeviceAlias <shareable|exclusive instance> 
<wait|notify>” 

*/ 

pCommand = sprintf( szTemplate, “acquire %s % s %s”, 
pszDeviceAlias, 

(^pszOwnership) ? pszOwnership : “ ”, 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? NULL : hWndNotify, 

0 ); 


return( ulRC ); 

} 


Figure 11-20. AcquireDevice—Requests ownership of a device instance, mciapi.c 

The AcquireDevice function makes a request to MMPM/2’s MDM (Media 
Device Manager) to take ownership of a particular device. Via the 
pszOwnership parameter, PlayRec will specify whether the device is to be 
allowed to be shareable or to be exclusively owned by the application. When 
PlayRec is in Recorder mode the device will be requested exclusive for the 
simple reason that we do not want the device becoming inactive in the middle 
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of a record operation. On the other hand, if we are playing back audio in 
Player mode, we can allow the device to be freely shared among the devices in 
the system. 

Now that we have ownership of the device, it is important to remember that 
with ownership of a device, comes the responsibility to share with other appli¬ 
cations, as necessary. To accomplish this, when you’re done utilizing a device 
instance, it should be returned, or released, back the MMPM/2. This is demon¬ 
strated in the ReleaseDevice function which will provide a mechanism for 
doing this. 


/* 

Release the Instance for the specified device alias 

*/ 

ULONG ReleaseDevice( PSZ pszDeviceAlias , BOOL bShare, PSZ pszReturn, 
HWND hWndNotify ) 


ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for “Release”: 

“release DeviceAlias <return resource> <wait|notify> 

*/ 

pCommand = sprintf( szTemplate, “release %s %s %s”, 
pszDeviceAlias, 

(bShare) ? “return resource” : “ ” , 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(!hWndNotify) ? NULL : hWndNotify, 

0 ); 


return( ulRC ); 

} 


Figure 11-21. ReleaseDevice—Relinquishes ownership of a device instance to the 
MCI, mciapi.c 
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Sending a release command to the MCI will cause the application to relin¬ 
quish ownership of the device specified by pszDeviceAlias. The bShare para¬ 
meter specifies whether the instance of the device should be returned fully 
shareable or not. Note that, when the release is performed with the return 
resource keywords as modifiers, the device instance can become inactive. The 
MCI will notify the application when the instance is made inactive, and when 
it is gaining or losing ownership of a device instance, at this time, an applica¬ 
tion should make certain that any state variables based on ownership or 
active/inactive state of the device are updated to reflect the changes to the 
instance. 

When an application is finished using any particular device it should make 
certain to return it completely to the MDM for reuse by other applications. 


/* 

Close the specified Device Alias 

*/ 

ULONG CloseDevice( PSZ pszDeviceAlias, PSZ pszReturn, HWND hWndNotify ) 
{ 

ULONG ulRC=0L; 

CHAR szTemplate[255]; 

PSZ pCommand; 

PSZ pReturn = (*pszReturn ) ? pszReturn : ((PSZ)NULL); 
int iLen = (*pszReturn) ? strlen(pszReturn) : 0; 


/* 

Build the command string for iClosei: 

iclose DeviceAlias <wait|notify>i 

*/ 

pCommand = (PSZ)sprintf( szTemplate, “close Is %s”, 

pszDeviceAlias, 

( !hWndNotify ) ? “wait” : “notify” 

); 

ulRC = mciSendString( szTemplate, pReturn, iLen, 

(IhWndNotify) ? (HWND)NULL : hWndNotify, 
0 ); 


return( ulRC ); 

} 


Figure 11-22. CloseDevice—Closes access to a device alias, mciapi.c 



360 Developing Multimedia Applications Under OS/2 

The close command instructs the MCI to relinquish all resources associated 
with the device alias specified in the call. The device alias, and the device 
instance for it, will no longer be valid after this call is made. 

We have discussed the major topics pertinent to what was and is required 
for enabling an application to utilize the MMPM/2 (via the MCI) in a simple 
and concise manner. More functions are provided in the source code on the 
diskette which can be used to perform a variety of other necessary operations 
on devices or data. We must now focus on how the pieces are put together and 
built into an executable. 

Building and Testing the Application 

Once the initial process of developing the code for your application is done, it is 
necessary to build the application into an executable. To do this, we need a file 
called a makefile, which is where the process of building the application will 
be defined to the compiler and its associated tools and linker. The makefile is 
the file that acts as a roadmap for the compiler to put together the pieces of 
source code, resources, and other components into one complete executable. 


^j:**** ********************************************************** ********* 

# 

# MAKE file for PIayer/Recorder 

# 

# Assumes that the environment is set up for development. Specifically, 

# the compiler, linker, rc and ipfc should be in the path. Also, the 

# environment variables for the tools must be properly set, e.g. LIB, 

# INCLUDE, This should all be taken care of automatically by 

# installing the OS/2 Toolkit and the MMPM/2 Toolkit. 

# 

^j:***** ******************************************************* *********** 

CC = icc 

LINK = 1in k 3 8 6 

BASELIBS = DDE4MBS.LIB 0S2386.LIB MMPM2.LIB 

# 

# Compilation Switches 

# 


# 

/ G3s 

: Generate 386 code with no stack checking 

# 

/C+ 

: Compile only one module. 

# 

/ W3 

: Warning 1evel. 

# 

/ Gd- 

: Link to static C libraries. 


Figure 11-23. makefile for sample application , playrec.exe 
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# /Ms 

ii / Gm+ 

# /DIN C L_3 2 

# /Ti + 

# /Sm 

# /O- 

# 


Puts Toronto compiler into C6.0 migration mode. 
Use multithreaded libraries. 

Use IBM code. 

Generate debugging code. 

Generate debugging code. 

Turn optimization off. 


CFLAGS = /G3s /C+ /W3 /Ss+ /Gd- /Ms /Gm+ /DINCL_32 
DEBUG = /Ti+ /Sm /0- 


COMPILE = $(CFLAGS) 

# 

# Link Switches 

# 

# /map : Creates a listing file containing all public symbols. 

# /nod : Causes all default libraries to be ignored. 

# /noe : The linker will not search the extended dictionary. 

# 


LFLAGS = /map /nod /noe 
DBLNK = /CO 


all: piayrec.exe 
# EXECUTABLE: PLAYREC.EXE 

playrec.exe: mpplay.obj appdefs.obj prdlg.obj playrec.def mpplay.res \ 
meia pi.obj 

$(LINK) $(DBLNK) mpplay.obj mciapi.obj appdefs.obj prdlg.obj, \ 

playrec.exe, playrec.map $(LFLAGS) /ST:20000, $(BASE LIBS), \ 
piayrec.def 
$(RC) playrec.res 
mapsym piayrec 

mpplay.obj: mpplay.c mpplay.h appdefs.obj prdlg.obj mciapi.obj 
$(CC) $(COMPILE) $(DEBUG) mpplay.c 

appdefs.obj: appdefs.c mpplay.h 

$(CC) $(COMPILE) $(DEBUG) appdefs.c 

mciapi.obj: mciapi.c mpplay.h appdefs.h 
$(CC) $(COMP IL E) $(DEBUG) mciapi.c 

prdlg.obj: prdlg.c mpplay.h 

$(CC) $(COMPILE) $(DEBUG) prdlg.c 


Figure 11-23. makefile for sample applicationplayrec.exe (Continued) 
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playrec.res: playrec.rc appdefs.h mpplay.h playrec.ico 
rc -r playrec.rc 


Figure 11-23. makefile for sample application , playrec.exe (Continued) 

In Figure 11-23, is the listing for our makefile, which sets up all the depen¬ 
dencies the for the executable named playrec.exe. Each portion of the applica¬ 
tion, “C” source code files, the .RC resource definition file has an associated 
tool. 
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MMPM/2 Device and Software Support 


INTRODUCTION 


This section lists and describes the MMPM/2 device support for audio adapters, 
video capture adapters, CD ROM drives and Laserdiscs. This list was current 
as of the writing of this book. Updates to this set of devices can be obtained 
from IBM. 


AUDIO ADAPTERS 


The following list describes the audio adapters supported by MMPM/2, and 
where to obtained the MMPM/2 drivers for them. 


CARD 

BUS 

Available From 

BBS or library 
location 

Sound Galaxy Nova 16 
(Aztech System Ltd.) 

ISA 

CompuServe or Aztech BBS 

501-623-8933 or 
OSUSER library 

Sound Blaster 
(Creative Labs) 

ISA 

MMPM/2 

408-428-6660 

Sound Blaster Pro 
(Creative Labs) 

ISA 

MMPM/2 

408-428-6660 


Figure 12-1. Audio adapters supported by MMPM/2 
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CARD 

BUS 

Available From 

BBS or library 
location 

Sound Blaster Pro MCV 
(Creative Labs) 

MCA 

MMPM/2 

408-428-6660 

Sound Blaster Pro 16 ASP 
(Creative Labs) 

ISA 

MMPM/2 

408-428-6660 

Sound Blaster 
(Creative Labs) 

ISA 

MMPM/2 

408-428-6660 

PORTABLE Sound 

Plus (DSP Solutions) 

pp(D 

DSP Solution BBS 

415-494-1621 

AudioDrive 

(ESS Technology Inc.) 

ISA 

CompuServe 

OS2USER library 

Audiovation Adapter 
(IBM) 

ISA 

Driver shipped with 
hardware 


Audiovation Adapter/2 
(IBM) 

MCA 

Driver shipped with 
hardware 


BusinessAudio 

(2) 

CompuServe 

OS2Support Library, 
Devices— 
BUSAUDIO.ZIP 

IBM M-Audio Capture 
and Playback Adapter 
(IBM) 

ISA 

MMPM/2 


IBM M-Audio Capture 
and Playback Adapter 
(IBM) 

MCA 

MMPM/2 


Jazz 16 (OEM) 
(MediaVision) 

ISA 

Available from system 
provider 

510-770-0527 

Memphis MM Unit 

ISA 

MediaVision BBS 

510-770-0527 

Pro Audio 3D 

ISA 

MediaVision BBS (Beta) 

510-770-0527 

Pro Audio Spectrum 16 

ISA 

MMPM/2 

510-770-0527 


Figure 12-1. Audio adapters supported by MMPM/2 (Continued) 
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Key: 

1. PP stands for Parallel Port. 

2. Business Audio is integrated into systems 

NOTE: For those devices that are Soundblaster compatible, the drivers 
will be initialized and operate normally under Soundblaster Pro2-level 
compatibility . 


VIDEO CAPTURE ADAPTERS 


Card 

BUS 

NTSC 

PAL 

INPUTS 

OVERLAY 

MAX RES 

SQ 

VC A/2 

MCA 

X 


CRS 


640X480 

BA 

VC A/2 PAL 

MC 


12 

CRS 


640X480 

BA 

SUPERVLA/MC 

(NTSC) 

MC 

X 


cs 


640X480 

D+B+ 

SUPERVIA/MC 

(PAL) 

MC 


2 

cs 


640X560 

D+B+ 

SUPERVIA/PC 

(NTSC) 

ISA 

X 


cs 


640X480 

DB+ 

SUPERVIA/PC 

(PAL) 

ISA 


X 

cs 


640X560 

DB+ 

QUICKVIA 

ISA 

X 


cs 


320X240 

AB 

QUICKVLA 

(PAL) 

ISA 



cs 


320X240 

AB 

QUICKVIA/MC 

MC 

X 


cs 


320X240 

AB 

QUICKVIA/MC 

(PAL) 

MC 


X 

cs 


320X240 

AB 

WINMOVIE 

ISA 

X 


cs 


320X240 

AB 

WINMOVIE 

(PAL) 

ISA 



cs 


320X240 

AB 

VIDEO 

BLASTER 

ISA 

X 

X 

C3 

X 3 

640X480 

CB+A 

VIDEO 

MAGIC 

ISA 

X 

X 

C3 

X 3 

640X480 

CB+A 


Figure 12-2. Video capture adapters supported by MMPM/2 
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Card 

BUS 

NTSC 

PAL 

INPUTS 

OVERLAY 

MAX RES 

SQ 

SUPER VIDEO 
WINDOWS 

ISA 

X 

X 

C3 

X 3 

640X480 

CB+A 

SUPER 

VIDEO 

WINDOWS/MC 

MC 

X 

X 

C3 

X 3 

640X480 

CB+A 

VIDEO 

CLIPPER 

ISA 

X 

X 

C3 

X 3 6 

640X480 

CB+A 

WAVEWATCHER 

ISA 

X 

X 

C3 

X 3 6 

640X480 

CB+A 

M&M BASIC 

ISA 

X 

X 

C3 1 S3 

X 3 6 

640X480 

CB+A 

WIN/TV 

ISA 

X 

X 

C3 SI 

TV 

X 3 6 

640X480 

C AA 


Figure 12-2. Video capture adapters supported by MMPM/2 (Continued) 


Key: 

1 The edges of the PAL image are not digitized. 

3 Card requires a VGA feature connector, and VGA mode display. The over¬ 
lay cards require the monitor to be in 640x480x16, 640x480x256, 
800x600x16 or 800x600x256. 

4 Requires VGA mode display. 

5 First MC card not available yet (should work with ISA code). 

6 Not in MMPM/2 1.1 but will work if Video Magic driver is selected. 

C Composite input. 

C3 Three different composite inputs. 

R RGB (Red Green Blue) input. 

S S-VHS or Y/C input. 

TV Television Tuner Support. 

S Column—Speed Ranking, frames per second captured. The cards are all 
close in speed. Doing real-time Ultimotion compression at 160x120 on a 
386SX 33Mhz ISA bus PC; 

“A” is approximately 18 frames per seconds 

“D” is approximately 12 frames per seconds 
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Q Column—Image Quality, Top Grade = digitized image quality; Bottom 
Grade = Overlay image quality. The overaly function provided by the 
overlay cards is a big plus though if you are going to be using the card to 
monitor live video. One minor drawback of the overlay cards is the only 
adjustment that applies to the digitized is tint (not brightness, color or 
contrast). This is usually not a problem unless your source (video input) is 
of poor quality. 

Max Res—Maximum resolution for the digitized image. For most video cap¬ 
ture 320x240 digitized images will be the largest practical size (speed and 
space). Some cards will allow you to capture larger sizes which may be 
more useful if you wish to capture large detailed bitmaps. The size of the 
image captured by the overlay cards are approximate as the cards need to 
go through a setup/alignment process where the size will be adjusted, 
usually is a little larger than 640x480 (especially if the input signal is 
PAL). 

Video Clipper and WaveWatcher cards were tested after the shipment of 
Video IN. They will not appear in the MMPM/2 documentation or install list, 
but if you select the Video Magic card during install of Video IN they will work. 

Overaly—Allows one to show live video in a window of any size on the desk- 
topfull screen 30 frames per second). Video in the window looks like TV. 
Function provided by these cards are similar to IBM’s M-Motion Overaly 
card. 

Video—Hardware Accelerated or Frame Buffer 

Most video adapters employed in PCs today can be placed into one of two cate¬ 
gories: Hardware Accelerated or Frame Buffer based. The major differ¬ 
ence between these two types of boards, as relates to multimedia, is only: 
speed. Frame buffer-based adapters simply provide a window into the memory 
on the adapter into which the display driver (or an application performing 
direct video access) can write. Hardware accelerated adapter provide assis¬ 
tance in hardware for such common functions as line drawing, palette modifi¬ 
cation, and bit-blitting. Immediately the differences in performance can be had 
by employing hardware acceleration. This performance does not come without 
a cost, although the cost differential has diminished to a great extent because 
more and more chipset manufacturers are producing hardware accelerated 
chipset solely. Important to MMPM/2 is support for the DIVE interface which 
is employed by SMV. Luckily, most of the accelerated video adapters have had 
supported for DIVE incorporated into them. The variety of boards vary by the 
chipset they are based on. Most boards available today are based on DRAM 
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(S3-801/805, Tseng ET-4000/w32, WD 90C2X/3X, Cirrus Logic 5426, and CT 
6553x based boards) memory for their video buffer. The faster video boards 
(S3-928/964, Weitek P9001/9001, Matrox MGA, and ATI Graphics 
Mach32/Mach64 based boards) employ VRAM (Video Ram), which is specifical¬ 
ly designed to enhance video performance. The faster VRAM based boards also 
carry a $100 (average) price premium over their DRAM based bretheren, 
although this gap is also closing. Cost conscious comsumers may opt to settle 
on some of the higher end DRAM based boards, while some may splurge to 
upgrade to a faster VRAM based board. 

So far, we have only discussed the accelerated video adapters, and we have 
not mentioned the frame buffer based boards. The vast number of VGA or 
SVGA based boards today are still by and large based on this technology. What 
we mean by this is that the installed based of systems based on these video 
adapters is still the majority. So, to adequate test the performance of any 
movie that it authored, remember to test on not just one, but perhaps two of 
these types of boards along with any hardware accelerated boards being used. 
For frame buffer boards, more dependencies on the system hardware the 
adapter is running in, since the CPU is the one drawing everything on the 
screen. Thus, a faster CPU, and or system bus, will improve performance, 
although what percentage itself, may vary. 

Here are some of the more common video chipsets/boards available today, 
who provides the drivers, the chipset type, the type of video system they are 
based on, and what type of video memory they employ: 


Video Chipset 

Provides video 
drivers 

Chip Types 

Video Type 

Video Memory 

IBM, Corp. 

IBM 

XGA-2 

HW 

VRAM 

Radius 

IBM & Radius 

XGA-2 

HW 

VRAM 

S3, Inc. 

IBM & Vendors 

801/805/864 

HW 

DRAM 

S3, Inc. 

IBM & Vendors 

928/964 

HW 

VRAM 

Tseng, Inc. 

IBM 

ET-4000 

FB 

DRAM 

Tseng, Inc. 

IBM & Vendors 

ET-4000/w32 
and w32i 

HW 

DRAM/VRAM 

Western Digital 

IBM & Vendors 

WD 90Clx/3x 

HW 

DRAM 

Cirrus Logic 

IBM & Vendors 

CL-GD542x, 

GD5401 

FB 

DRAM 


Figure 12-3. Video Adapter Types supported by OS/2 
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Video Chipset 

Provides video 
drivers 

Chip Types 

Video Type 

Video Memory 

ATI, Inc. 

ATI, Inc. 

Mach 32/ 

Mach64 

HW 

VRAM 

ATI, Inc. 

ATI, Inc. 

688xx 

HW 

DRAM 

ATI, Inc. 

IBM 

28801 

FB 

DRAM 

ATI, Inc. 

ATI, Inc. 

Mach32/ 

Mach64 

HW 

VRAM 

Matrox, Inc. 

Matrox, Inc. 

Matrox MGA 

HW 

VRAM 

HeadLand Tech. 

IBM 

HT-209 & 

S3 86c801 

FBCHT-209), 
HW (S3) 

DRAM 

Trident Micro. 

IBM & Trident 

TVGA8900/9000 

FB 

DRAM 

Weitek, Inc. 

Weitek & 

Vendors 

P9000/P9001 

HW 

VRAM 


Figure 12-3. Video Adapter Types supported by OS/2 (Continued) 


Here is a list video adapters listed by manufacturer and chip type, as accu¬ 
rate a list as we were able to prepare for, where drivers for these adapters are 
available presently. 


Chipset 

Video Adapter name 

BBS or Driver Location 

ATI 68800 

ATI Graphics Ultra 

905-764-9404,BBS 

ATI Mach 32 

ATI Graphics Vantage, Ultra*, 
Ultra Pro, Integra 

a » 

ATI Mach 64 

ATI Graphics ProTurbo 

a » 

ATI 28800 

ATI VGA Wonder XL 

a n 

Cirrus Logic CL-GD5420, 
26,28,29 

Diamond SpeedStar 24x, 

SpeedStar Pro, Actix ProStar VL 

(510)-226-7220, also 
(See 1) 

Cirrus Logic CL-GD5401 

Boca Research VGA004/006 

Std. in OS/2 2.1+ 

Matrox MGA 

Matrox MGA Vram 

1-800-361-1408 


Figure 12-4. Adapters classified by Chipset and driver availability 
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Chipset 

Video Adapter name 

BBS or Driver Location 

Western Digital 

90C10/11 (512K) 

Paradise VGA Pro, VGA 

1024, “PVGA” 

714-753-1234,BBS 

Western Digital 

90C30 (lmeg) 

MVGA 1024DX 

« » 

Western Digital 90C31/33 

Diamond SpeedStar 24X 

Diamond Systems(l) 

S3 (86C928/964) 

Actix GraphicsEngine 32, 

Diamond Stealth32, STB Pegasus 

Actix Systems, Diamond 
Systems(l), and STB (2) 

S3 (86C801/805) 

STB PowerGraphVL-24 / Wind/X, 
Orchid Farhrenheit 1280, 

Diamond Stealth, Actix 
GraphicsEngine 

(See 1,2, and 3) 

Trident 8900 B/C 

Trident 8900, Hi Res 512 

Trident Microsystems, Std 
in OS/2 2.1+ 

Tseng ET4000 

Orchid Pro Designer II, 

Ultra SVGA, STB Powergraph, 
STB Ergo VGA, TTX MegaView, 
Optima Mega SVGA, Diamond 
SpeedStar and Speedstar+, 

Wyse SmartVision, 

Orchid Systems, (See 1 & 2), 
Std. in OS/2 2.1+. 

Tseng ET4000/w32 

STB Lightspeed VL, Hercules 
Dynamite D20x,D30x, D501, 

D60x, and D90x series 

(See 2 & 4) 

Tseng ET4000 & 

Sierra RAMDAC 

Swan Palette Plus, 2TheMax 

VGA 4000, Diamond SpeedStar + 
HIcolor, STB Ergo VGA 
(RAMDAC optional) 

Std. in OS/2 2.1+, 

(See 1 & 2) 

Video 7 VGA (Headland) 

Video 7 VRAM, Video 7 Fastwrite 

Std. in OS/2 2.1+ 

Weitek P9000/9100 

Diamond ViperVRAM, 

Orchid Celcius 

Weitek Systems, for 

Diamond Viper (See 1) 


Figure 12-4. Adapters classified by Chipset and driver availability (Continued) 

Key: 

1 Diamond Systems BBS (408) 524-9301 

2 STB Systems BBS (214) 437-9615 
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3 S3 Drivers are shipped with OS/2 from 2.11 on, and are available via 
CompuServe, OS2USER Library, S3-16M package, as well as from board 
vendors. 

4 Hercules Technology, Inc. BBS (510) 623-7449 


These lists should provide a good idea of some of the options available in 
video hardware and help in making a selection. Where we refer to VENDORS 
in the tables, we refer to those hardware manufacturers that produce a name 
brand video adapter. Given the number of video hardware manufacturers, it 
would be a wise idea to investigate what chipset the board you’ve selected is 
based on. 

CD-ROM DEVICES SUPPORTED BY OS/2 AND MMPM/2 


Following table lists the CD-ROM drives supported by MMPM/2 as of the writ¬ 
ing of the book. 


DRIVE 

Volume Level 

XA Support 

Can Stream 

CD Technology 3301 

16 

Y 

N 

Hitachi 1750 

2 

N 

N 

Hitachi 1650, 3650 

2 

N 

N 

Hitachi 3750 

2 

Y 

N 

IBM CD-ROM I 

2 

N 

N 

IBM CD-ROM II 

16 

Y 

N 

IBM CD-ROM Enhanced II 

16 

Y 

N 

NEC 25, 35, 36, 37 

2 

N 

N 

NEC 38 

2 

Y 

N 

NEC 72, 73, 74, 77, 80, 82, 83, 84 

2 

N 

N 

NEC 74, 84 Multispin 

2 

Y 

N 

NEC 3xe, 3xi 

32 

Y 

N 


Figure 12-5. OS/2 supported CD-ROMs 
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DRIVE 

Volume Level 

XA Support 

Can Stream 

Panasonic 501, MC501S 

1 

N 

N 

Philips LMS CM206 

2 

Y 

N 

Pioneer 604 

101 

Y 

N 

Sony 31A 

20 

Y 

N 

Sony 541, 6211, 7211 

33 

Y 

N 

Sony 561 

33 

Y 

Y 

Sony 6111 

2 

N 

N 

Texel 3020, 3021,3120 

2 

N 

N 

Texel 3024, 5024 

2 

Y 

N 

Texel 3024, 5024 MS 

2 

Y 

N 

Texel 5020, 5021, 5120 

2 

N 

N 

Toshiba 3101, 3201 

2 

N 

N 

Toshiba 3301 

16 

Y 

N 

Toshiba 3401 

16 

Y 

Y 

Toshiba 4101 

16 

Y 

Y 


Figure 12-5. OS/2 supported CD-ROMs (Continued) 


LASERDISC DEVICES SUPPORTED BY MMPM/2 

The following laserdiscs are support by MMPM/2: 

• Pioneer LD-V4200 

• Pioneer LD-V4300D 

• Pioneer LD-V4400 

• Pioneer LD-V8000 

• Pioneer LD-V800 

• Pioneer LD V2200 
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• Pioneer CLD V2400 

• Pioneer CLD V2600 

In addition to the previous list of supported laserdisc, the following set is 
also supported and ship with the M-MNotion control Program 2.01. 

• Pioneer 6000 Family (LD-V6000, LD-V6000-1, LD-V6010-A) 

• Sony Family (LDP-1450, LDP-1165, LDP-1550, LDP-1750, LDP- 
2000, LDP-3600D 

® Pioneer LDM2000, LDM1000 

MULTIMEDIA DEVELOPMENT TOOLS 


This section provides a list of MMPM/2 development applications and tools. 
These programs and tools can be used to develop and test MMPM/2 applica¬ 
tions as well as multimedia titles. This list is by no means complete, but it is 
provided as a starting point for MMPM/2 application developers. 


MCI++ 


At the time of the writing of this book, IBM had in Beta form, a object oriented 
interface to the MCI interface. This is a C++ class library for the IBM C Set/2 
compiler. 

icon Author by AimTech, Inc. 

IconAuthor® is a multimedia presentation authoring tool developed by 
AimTech, Inc. It provides an icon-based interface for developing scripts. There 
are a variety of iconic “instructions” which represent program steps. There are 
specific icons for supporting playback of waveaudio, MIDI, and SMV files. 
There are iconic for branching, looping, creating subroutines, and other pro¬ 
gramming style operations. The purpose and function of this program is to pro¬ 
vide a visual programming facility for multimedia presentations. The user 
interface is simple enough for most novices to create some presentations in a 
short period of time. The more complex functions will require more art and 
media presentation skills to put together more involved presentation, especial¬ 
ly if you deal with multiple “cast members” or actor objects within an anima¬ 
tion. There is support for object collision detection so that events and 
sequences can be created whereby actors interacting with other objects can 
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produce a wide variety of effects. This tool allows you to create functions your¬ 
self and then puts pieces together to perform new functions. This tool retails 
for $4995.00. 


MediaSCRIPT OS/2 by Network Technology Corporation 

This tools allows for multimedia authoring under MMPM/2 natively, also sup¬ 
porting DVI technology via the Action Media/2 card. It provides a point-and- 
click development environment tied to a programming language based script. 
MEDIAScript allows the capture of video and images, as well as audio via 
built-in tools. The product provides an interface to multimedia under OS/2 via 
its MMS (or MultiMedia Server), which is where the command-driven interface 
is provided. For authoring there is a separate application for designing the 
user interface for your application or presentation, this is called the AUI, or 
Authoring User Interface designer. Any script created under the AUI can be 
previewed, or run immediately via the MMS. The AUI allows for creation of 
complex presentations without dealing with the underlying programming lan¬ 
guage of MMS. The AUI provides support for various type of screen effects, 
video mixing and playback. MEDIAScript also support what is called frame, or 
cel animation where a sequence of still image are blended together to produce 
the effect of motion. There are two type of MEDIAScript product currently 
available: MEDIAScript OS/2 Desktop Edition, and MEDIAScript OS/2 
Professional Edition. The Professional Edition provides additional facilities 
(such as support for programming directly to MEDIAScript’s internal program¬ 
ming language, and enhance authoring facilities). 

Prominare Designer by Prominare Inc. 

The Prominare Designer product and its integrated visual application design 
environment are not a direct multimedia authoring package. However, this 
tool is the only one we know of that allows a developer to visually create 
dialogs, windows, utilize MMPM/2 controls, and create custom controls from 
within its environment. The designer supports all the standard MMPM/2 con¬ 
trols including circular sliders, and graphic (including animated) buttons. The 
designer will also generate code for all PM user interface pieces designed under 
it, including support for client area-based controls (or Secondary Windows). 
Prominare, Inc. can be contacted at (416) 363-2292. 
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Ultimedia Tools Series 

The following products from IBM comprise the Ultimedia Tools Series: 

• Ultimedia Builder/2 

• Ultimedia Perfect Image/2 

• Ultimedia/2 

• Ultimedia Video IN/2 

All of these products run on OS/2 2.1 and take advantage of MMPM/2. 
Ultimedia Builder/2 

Ultimedia Builder/2 is a 32-bit multimedia authoring tool. It has a scripting 
editor with a graphical front end for the creation of multimedia presentation 
applications. Builder/2 supports the Workplace Shell drag-and-drop of multi- 
media objects. It provides a graphical or text user interface, and it also 
includes audio, image, and video browers, text plane support, and a simple ani¬ 
mation editor. The graphical editor gives users a visual representation of a 
filmstrip-like format that shows the sequence of multimedia objects in the pre¬ 
sentation. 

Ultimedia Perfect lmage/2 

Perfect Image/2 is an image capture, convert text editor, image enhancement, 
and print tool for creating high quality multimedia objects. It is a tool suitable 
for the novice or the experienced multimedia creator. Perfect Image/2 enables 
users to enhance, retouch or rearrange images in popular true color formats. It 
has a file conversion function, performing conversions across image formats, 
including Windows and OS/2 bitmaps, TIFF, Targa, PCX, AVC, and others. 

Ultimedia Workplace/2 

Workplace/2 is an innovative multimedia object manager that is equally valu¬ 
able for business users and creative professionals. Its ease-of-use, rich func¬ 
tionality and graphical interface make it well-suited for professional multime¬ 
dia authors and business users who need to manage large numbers of multime¬ 
dia objects easily. Workplace/2 offers new desktop management capabilities 
that simply the challenging task of organizing, playing, annotating, and 
searching and retrieving large numbers of multimedia objects, such as images, 
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video, audio, and text. Objects are represented by 256 color icons, which can be 
draggedand dropped to execute other tools associated with the use of multime¬ 
dia objects, such as story editors, image editors and draw programs. Users can 
also access existing SQL databases (such as DB@/2 and dBase IV), access the 
extended attributes of the multimedia file, associate an object with an individ¬ 
ual SQL record, and create multimedia databases for existing applications. 

Ultimedia Video IN/2 

Ultimedia Video IN/2 is an award winning product for capturing and editing 
video. It is a complementary product to the software video playback functions 
of MMPM/2 for OS/2 2.1. Video IN/2 includes both a video capture application 
and editing application for creating digital video movies. It supports a wide 
range of video capture cards. See the table on video capture cards above. Video 
IN/2 supports IBM’s Ultimotion and Intel’s Indeo digital video compression 
algorithms. 

DV!/Action Media II 

In addition to the software, motion video features of MMPM/2, IBM also sup¬ 
ports the Action Media II card for playback and recording of Digital Video 
Interactive or DVI movies. This support comes in the form of a Media Control 
Device for the Action Media II card. This software is shipped with the Action 
Media II adapter. It supports the same set of digital video MCI commands. The 
file format it uses is AVS. This file format is not supported by MMIO. 

Ultimotion Video Data Format No-Cost License 

IBM offers a no-cost license for its Ultimotion software video technology. The 
Ultimotion Development Kit, including the license for Ultimotion, Ultimotion 
data stream documentation, the beta windows decompressor, and sample 
Ultimotion files is available at no charge to qualified developers. To order it in 
the U.S. and Canada, contact IBM Worldwide Industry Hardware support at 
(800) 426-4579 ext. 200. In the U.S. and worldwide, fax requests on company 
letterhead to (708) 635-3620. The Ultimotion Development Kit (with only one 
sample movie file) is also available online at the following locations: 

• Prodigy (IBM Device Driver in the OS/2 Club Download Library) 

• CompuServe (OS/2 Support, Library 17, IBM files) 

• Internet (software.watson.ibm.com in the os2\pubs\misc directory 
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An Ultimotion source code license is also available from IBM. For general 
information on Ultimotion, an Ultimotion Source Code License, Ultimotion 
Video IN or OS/2 Multimedia, send a note to ULTIMOTION@vnet.ibm.com. 
Ultimedia Video IN/2 is now available as part of the OS/2 Warp Bonus Pack. 
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Media Control Interface 


This section describes the Media Control Interface APIs, messages, and data 
structures. Updates and corrections to the MMPM/2 Toolkit Programming 
Reference are included in this appendix. 

mciGetDevicelD 


mciGetDevicelD 

Get the device ID corresponding to an alias of a device. The ID can then be 
used on subsequent MCI Procedural commands. 


//define INCL_MCI0S2 
//include <os2me.h> 

ULONG mciGetDevicelD (PSZ pszName) 


Parameters 

pszName (PSZ)—input 

Alias name. This alias name was input on the open or connection com¬ 
mands. 

Return Values 

The return value is the device ID assigned to this alias when the device was 
opened or when the connection command with the query flag was issued. If the 
return value is 0, then the alias is not a valid alias. 


379 
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mciGetErrorString 


mciGetErrorString 

Get the textual string associated with the given error code. 


//define INCL_MCI0S2 
//include <os2me.h> 

ULONG mciGetErrorString (ULONG ulError, 

PSZ pszBuffer, 
USHORT usLength) 


Parameters 

ulError (ULONG)—input 

Error code. The low-order word contains the error code, and the high- 
order word contains the device ID. The device ID is used by MMPM/2 to 
determine if there are device-dependent errors. If there are device-depen¬ 
dent errors, then MMPM/2 returns the device-dependent error string. 

pszBuffer (PSZ)—input/output 

Point to application’s buffer. The textual error string will be copied to this 
buffer based on the length of the buffer. 

usLength (USHORT) —input 

Size of application’s buffer. 

Return Values 

MCIERR_SUCCESS MCIERR_OUTOFRANGE 

MCIERR_INVALID_DEVICE_ID MCIERRJNVALIDJBUFFER 

Remarks 

If the size of the application’s buffer (usLength) is smaller than the size of the 
error string to be returned, then only usLength bytes of the error string will be 
copied into the application’s buffer. A buffer size of 128 bytes is recommended 
to avoid this problem. 
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mciQuerySysValue 


mciQuerySys Value 

Query the value of system defined attributes. 


#define INCL_MCI0S2 
#include <os2me.h> 

ULONG mciQuerySysValue (USHORT iSysValue, 

PVOID pValue) 


Parameters 

iSysValue (USHORT)—input 

System attribute. The possible system attributes are: 

MSV_CLOSEDCAPTION 

The possible return values are TRUE if the user has enabled closed cap¬ 
tion and FALSE otherwise. 

MSV_MASTERVOLUME 

The master volume setting. The range is 0 to 100. 

MSVJHEADPHONES 

TRUE if the user has headphones enabled for the system and FALSE 
otherwise. 

MSV_SPEAKERS 

TRUE if the user has speakers enabled for the system and FALSE 
otherwise. 

MS V_W ORKPATH 

The path when MMPM/2 creates temporary files, for example, 
(c:\mmos2\temp). 

MSV.SYSQOSVALUE 

System wide Quality of Service (QOS) specification value used for band¬ 
width reservation. 
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MSV.SYSQOSERRORFLAG 

Description of error occurring during band-width reservation. 
pValue (PVOID)—input/output 

Point to a return field. The type of data object that this points to is depen¬ 
dent on the attribute requested. 


System Attribute 

Data Type 

MSV_CLOSEDCAPTION 

BOOL 

MSV_MASTERVOLUME 

ULONG 

MSV.HEADPHONES 

ULONG 

MSV_SPEAKERS 

ULONG 

MSV_W ORKPATH 

PSZ 

MSV_SYSQOSVALUE 

ULONG 

MSV.SYSQOSERRORFLAG 

ULONG 


Return Values 

If the command completed successfully then MCIERR_SUCCESS is returned, 
or else non-zero is returned. 

Remarks 

Most of the system attributes can be changed by the user via the Multimedia 
Setup Pages. 
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mciSendCommand 


mciSendCommand 

This function sends a Media Control Interface message to MMPM/2. This API 
is also referred to as the procedural interface. 


#define INCL_MCI0S2 
#include <0S2ME.H> 

ULONG mciSendCommand (USHORT usDevicelD 
USHORT usMessage, 
ULONG ulParaml, 
PVOID pParam2, 
USHORT usUserParm) 


Parameters 

usDevicelD (USHORT)—input 

The device ID to which this message is to be sent. This field is ignored on 
the MCI_OPEN message. 

usMessage (USHORT)—input 

The Media Control Interface message to send. 

ulParaml (ULONG)—input 

Flags for this message. 

pParam2 (PVOID)— input 

Pointer to a data structure for this message. 

usUserParm (USHORT)—input 

User parameter returned in the notification for this message. 

Return Values 

This function will return MCIERR_SUCCESS in the low-order word of the 
return value if no error occurred. Otherwise it returns the error code in the 
low-order word of the return value. See the individual Media Control Interface 
messages for the possible error codes. 
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Remarks 


Use mciGetErrorString to get the textual error string for any errors returned 
by this function. 
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mciSendString 


mciSendString 

This function sends a Media Control Interface Command String to MMPM/2. 
This API is also referred to as the string interface. 


^define INCL_MCI0S2 
#include <os2me.h> 

ULONG mciSendString (PSZ pszCommand, 

PSZ pszReturnString, 

USHORT usReturnLength, 
HWND hwndCallback, 
USHORT usUserParm) 


Parameters 

pszCommand (PSZ)—input 

Media control command string. 

pszReturnString (PSZ)—input/output 

An application supplied buffer for return data. This pointer can be NULL if 
no return information is desired. 

usReturnLength (USHORT)—input 

Size of application’s return buffer. 

hwndCallback (HWND)—input 

A PM window handle to call back if notify was specified in the command 
string. 

usUserParm (USHORT)—input 

User parameter returned in the notification for this message. 
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Return Values 

This function will return MCIERR_SUCCESS in the low-order word of the 
return value if no error has occurred. Otherwise it returns the error code in the 
low-order word of the return value. See the individual Media Control Interface 
messages for the possible error codes. 

Remarks 

If the pszReturnString parameter is NULL or the usReturnLength is 0 then no 
data will be returned. 
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mciSetSysValue 


mciSetSysValue 

Set the value of system defined attributes. 


//define INCL_MCI0S2 
//include <os2me.h> 

ULONG mciSetSysValue (USHORT iSysValue, 
PVOID pValue) 


Parameters 

iSysValue (USHORT)— input 

System attribute. See mciQuerySysValue for a list of possible system 
attributes. 

pValue (PVOID) —input/output 

Pointer to a value to be set. The type of data object that this points to is 
dependent upon the attribute requested. See mciQuerySysValue for a list 
of data types. 

Return Values 

TRUE if the functions succeeds, FALSE otherwise. 

Remarks 

Most of the system attributes can be changed by the user via the Multimedia 
Setup Pages. 
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mciPlayFile 


mciPlayFile 

This function plays a multimedia data file using Media Control Interface 
Commands. 


#define INCL_MACHDR 
#define INCL_MCI0S2 
#include <os2me.h> 

ULONG mciPlayFile (HWND hwndOwner, 

PSZ pszFile, 

ULONG ulFlags, 

PSZ pszTitle, 

HWND hwndViewport) 


Parameters 

hwndOwner (HWND) —input 

Window handle of the owner window. If this parameter is NULL, the cur¬ 
rently active window is used. 

pszFile (PSZ) —input 

Pointer multimedia file name. Compound file names are also supported (i.e., 
a:\path\file+element). 

ulFlags (ULONG) —input 

MCI_OWNERISPARENT 

Indicates that the owner window should be used as the parent window for 
any default window that is created. If this flag is passed to a device that 
does not support a parent window, an error is returned. 

MCI.STOPACTIVE 

Indicates that any currently active command issued by either 
mciPlayFile or mciPlayResource should be stopped. 

MCI.ASYNC 

Indicates that the command should be processed synchronously. A ren¬ 
dezvous command will not be done. 



APPENDIX A: Media Control Interface 389 


MCI.ASYNCRENDEZVOUS 

Indicates that the command should be processed synchronously. A ren¬ 
dezvous command will be done. 

mci.rendezyous 

Indicates that the call should wait for a currently pending asynchronous 
command to complete. 

® If no command is pending, it returns immediately. 

• If an asynchronous command is not pending, this function will return 
immediately. This flag indicates that the command should wait until 
a pending asynchronous play command completes and then returns. 

® If a synchronous (default) play command is pending, this command 
should return immediately with MCIERR_NO_ASYNC_ 
PLAY.ACTIVE. 

® If another MCX_RENDEZVOXJS command is pending, this command 
should return immediately with a MCIERR_NO_ASYNC_ 
PLAY_ACTXVE. 

pszTitle (PSZ)—input 

Title for window if one is generated. The title is ignored if a window would 
not be generated. 

hwndViewport (HWND)—input 

Window handle for displaying the video image. If a viewport window is not 
specified, then a default video window is displayed. This parameter only has 
an effect when the data type supports video. 

Return Values 


MCIERR.SUCCESS 

MCIERR_NO_ASYNC_PLAY_ACTIVE 

MC1ERR_MISSING_PARAMETER 

MCIE]RR_FIIE_A1TRIBUTE 

MCIERR_INSTANCE_INACTIVE 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_DEVICE_LOCKED 


MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_FLAGS_NOT_COMPATBBLE 

MCIERR_FILE_NOT_FOUND 

MCIERR_DUPIJCATE_ALIAS 

MCIERR_I]WAIJD_BUFFER 

MCIERR_CANNOT_LOAD_DRIVER 

MC1ERR_INVALID_CALLBACK_HANDLE 

MCIERR_OUT_OF_MEMORY 
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Remarks 


This API provides for a simple way of playing a multimedia data file. It sup¬ 
ports any multimedia file type or RIFF compound files. 

The audio is played on the default MCI device. A device control panel is not 
displayed for audio. 

Still images are not supported. 

For video, the default MCI driver window is displayed. The movie is played 
from beginning to end. The window is destroyed when the device is closed. If a 
hwndViewport window is specified, then the video will be shown in the view¬ 
port window. 

The default is to play the file synchronously unless the MCI_ASYNC or 
MCI_ASYNCRENDEZVOUS flag is specified. The queue message is 
processed during its processing. 

When the file name that is passed is a NULL pointer or an empty buffer, then 
the MCIERR_MISSING_PARAMETER error is returned unless the 
MCI_STOPACTTVE or MCI_RENDEZVOUS flags are set. In order to stop a 
currently active command, use the MCI_STOPACTTVE flag. 

Either mciPlayFile or mciPlayResource could return a 
MCIERR_NO_ASYNC_PLAY_ACTIVE error. This indicates that no asyn¬ 
chronous play is currently active for the associated owner window. 

The title parameter can be NULL. If a title is specified and a window is dis¬ 
played, the title is used as the window title. A window is only displayed if a 
video file is played. 

When the pszFile parameter is specified and an active PLAY command is asso¬ 
ciated with the specified owner window, the first command is superseded by 
the second command. 
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mciPlayResource 


mciPlayResource 

This function plays a multimedia resource, such as a waveform, MIDI, or 
video, on the default device associated with the resource type. 


//def ine INCL_MACHDR 
//define INCL_MCI0S2 
//include <os2me.h> 

ULONG mciPlayFile (HWND hwndOwner, 

HMODULE hmod, 

ULONG resType, 

ULONG res ID, 

ULONG ulFlags, 

PSZ pszTitle, 

HWND hwndViewport) 


Parameters 

hwndOwner (HWND)—input 

Window handle of the owner window. If this parameter is NULL then the 
currently active window is used. 

hmod (HMODULE)—input 

Module handle of the module that contains the resource. The resource is 
loaded using DosGetResource. NULL indicates the program file’s resource. 

resType (ULONG)—input 

Defines the resource type with one of the following values: 

RT.WAVE 

Resource type is digital audio. 

RT_AVI 

Resource type is digital video using the AVI file format. 

RT_RMID 

Resource type is MIDI. 
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RT_RIFF 

Resource type is RIFF. 
resID (ULONG)—input 
Identifier for resource. 
ulFlags (ULONG)—input 

MCI.OWNERISPARENT 

Indicates that the owner window should be used as the parent window for 
any default window that is created. If this flag is passed to a device that 
does not support a parent window, an error is returned. 

MCI_STOP ACTIVE 

Indicates that any currently active command issued by either 
mciPlayFile or mciPlayResource should be stopped. 

MCI_ASYNC 

Indicates that the command should be processed synchronously. A ren¬ 
dezvous command will not be done. 

MCI_ASYNCRENDEZVOUS 

Indicates that the command should be processed synchronously. A ren¬ 
dezvous command will be done. 

MCX.RENDEZVOUS 

Indicates that the call should wait for a currently pending asynchronous 
command to complete. 

• If no command is pending, then it returns immediately 

® If an asynchronous command is not pending, this function will return 
immediately. This flag indicates that the command should wait until 
a pending asynchronous play command completes and then returns. 

• If a synchronous (default) play command is pending, this command 
should return immediately with MCIERR_NO_ASYNC_ 
PLAY_ACTIVE 

• If another MCI_RENDEZVOUS command is pending, this command 
should return immediately with a MCIERR_NO_ASYNC_ 
PLAY_ACTIVE. 
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pszTitle (PSZ)—input 

Title for window if one is generated. The title is ignored if a window 
would not be generated. 

hwndViewport (HWND)—input 

Window handle for displaying the video image. If a viewport window is 
not specified then a default video window is displayed. This parameter 
only has an effect when the data type supports video. 


Return Values 

MCIERR_SUCCESS 

MCIERR_NO_ASYNC_PLAY_ACTIVE 

MCIERR_MISSING_PARAMETER 

MCIERR_FILE_AITE1IBUTE 

MCIERR_INSTANCE_INACTIVE 

MCIERR_DUPLICATE_ALIAS 

MCIERRJNVAIJD_BUFFER 


MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVALID_CATJ,BACK_HANDLE 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_FIAGS_NOT_COMPATIBLE 

MCIERR_FILE_NOT_FOUND 

MCIERR_CANNOT_LOAD_DRIVER 

MCIERR_DEVICE_LOCKED 

MCIERR_OUT_OF_MEMORY 


Remarks 

This API provides for a simple way of playing a multimedia resource stored in 
a program resource. 

The audio is played on the default MCI device. A device control panel is not 
displayed for audio. 

Still images are not supported. 

For video, the default MCI driver window is displayed. The movie is played 
from beginning to end. The window is destroyed when the device is closed. If a 
hwndViewport window is specified, then the video will be shown in the view¬ 
port window. 

The default is to play the file synchronously unless the MCI_ASYNC or 
MCI_ASYNCRENDEZVOUS flag is specified. The queue message is 
processed during its processing. 

Either mciPlayFile or mciPlayResource could return a MCIERR_NO_ 
ASYNC_PLAY_ACTIVE error. This indicates that no asynchronous play is 
currently active for the associated owner window. 
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The title parameter can be NULL. If a title is specified and a window is dis¬ 
played, the title is used as the window title. A window is only displayed if a 
video file is played. 

If the resID is 0, then an MCIERR_MISSING_PARAMETER error is 
returned unless the MCI__STOPACTIVE or MCI_RENDEZVOUS flags are 
set. To stop a currently active command, use the MCI_STOPACTrVE flag. 
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mciRecordAudioFile 


mciRecordAudioFile 

This function records an audio file or MMIO compound audio file element. 


^define INCL_MACHDR 
#define INCLJCI0S2 
#include <os2me.h> 

ULONG mciRecordAudioFile (HWND hwndOwner, 

PSZ pszFile, 
PSZ pszTitle, 
ULONG ulFlags) 


Parameters 

hwndOwner (HWND)—input 

Window handle of the owner window. If this parameter is NULL, then the 
currently active window is used. 

pszFile (PSZ)—input 

Pointer multimedia file name. Compound file names are also supported (i.e., 
a:\path\file+element). 

pszTitle (PSZ) —input 

Specifies the title for the recorder window. 

ulFlags (ULONG)—input 

Reserved. Must be zero. 

Return Values 

MCIERR.SUCCESS 

MCIERR_MISSING_PARAMETER 

MCIERR__UNSUPPORTED_FLAG 

MCIERR_FILE_NOT_FOUND 

MCIERR_OUT_OF_MEMORY 



396 Developing Multimedia Applications Under OS/2 

Remarks 

This API provides a small, simple recorder window, which allows an object-ori¬ 
ented method of recording audio annotations. All play and record operations 
are from beginning to end. 

This call does not return, the recorder window is closed. The message queue is 
processed during the operation of this function. Once recording is completed, 
the window is dismissed. 

This API records 11kHz, mono, and PCM audio data from the microphone 
input of the default waveaudio device. The sample size defaults to the card 
default. 

This function creates the file if it does not exist. If a compound file name is 
specified (d:\path\file+element), the file will be created. If it does not exist, the 
element will be created after the record operation completes. 

The pszFile parameter, which specifies the name of the object to record into, is 
an input-only parameter. 

When the pszTitle is not specified, the last component of the file name or the 
MMIO element name is used. 

This function records only audio files. 
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MEDIA CONTROL INTERFACE COMMAND MESSAGES 


This section describes the Media Control Interfaces messages. The following 
flags are available for all MCI messages unless denoted in the remarks section 
of that message. 

ulPar am 1 (ULON G) 

This parameter can contain any of the following flags: 

MCI.NOTIFY 

A notification message (MM_MCINOTIFY) will be posted to the PM win¬ 
dow queue specified in the hwndCallback parameter of the data structure 
pointed to by the pParam2 parameter. The notification will be posted 
when the command is complete or when an error occurs. 

MCI_WAIT 

Control is not returned to the application until the command is completed 
or an error occurs. 
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MCI_ACQUIREDEVICE 


MCLACQUIREDEVICE 

This message requests that the given device instance be made active. It is also 
used to request either exclusive or exclusive instance rights for this 
instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_ACQUIRE_QUEUE 

If the acquire message cannot be executed immediately, then the message is 
queued for execution when the device resources are available. If a release or 
close message is issued while an acquire message is queued, then the 
acquire message is canceled. 

MCI.EXCLUSIVE 

Device resources are to be acquired exclusively for the device instance. No 
other device instance can use the device resource until a release or close is 
issued. 

MCI_EXCLUSIVE_INSTANCE 

This is similar to MCI_EXCLUSIVE, except that only the required amount 
of device resource is acquired exclusively. If more resource on the device is 
available, then other device instances can utilize it. 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR_SUCCESS MCIERR_INVALID_FLAG 

MCIERR_INVALID_DEVTCE_ID MCIERR_FLAGS_N OT_C OMPATIBLE 
MCIERR_DEVICE_LOCKED MCIERR_INVALID_CALLBACK_HANDLE 
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Remarks 

The application has three access modes for acquiring a device; shareable, 
exclusive instance, and exclusive. Shareable means that the device 
instance is a fully shareable resource. Exclusive instance mode guarantees that 
this device instance will not be made inactive and that the device resource will 
be fully utilized if possible by other device instances. The final mode guaran¬ 
tees that this device instance will not be made inactive and that the device 
resource is only used by this device instance. The preferred modes, in order, 
are: 

• shareable 

• exclusive instance 

• exclusive 

Even though the MCI_ACQUIREDEVTCE command completes successfully, 
applications do not gain use of the device until it receives the MM_MCIPASS- 
DEVICE message. This messages is posted (via WinPostMsg) to the window 
handle specified in the hwndCallback field on the MCI_OPEN 
message. 

Applications should utilize the WM_ACTIVATE message to decide when to 
issue the MCI_ACQUIREDEVICE message. This way an application that has 
PM focus or is interacting with the user will have use of the device resources. 
There are conditions when applications not in focus may require the use of 
multimedia device resources and, as such, should issue the acquire message 
to gain use of the device resource. 
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MCI_CAPTURE 


MCI_CAPTURE 

This message requests the digital video device to capture the current video 
image and store it as an image device element. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_CAPTURE_RECT 

Indicates that a region of the screen to be captured is provided in the 
MCI_CAPTURE_PARMS structure. The region is specified by the rect 
field of the MCI_CAPTURE_PARMS structure. 

MCI_CONVERT 

Specifies that the captured image data will be converted to the standard 
interchange format (BMP for images) when it is saved to disk. 

pParam2 (PMCI_CAPTURE_PARMS)—input 

A pointer to an MCI_CAPTURE_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR.DRIVER 

MCIERR_INVALID_FLAG 


MCIERR_UNSUPPORTED_FLAG 

MCIERR_INSTANCE_INACTIVE 

MCIERR_OVLY_INVALID_RECT 

MCIERR_OVLY_NOT_AVAILABLE 


Remarks 


This command is not supported by all devices. Applications should use the 
MCI_GETDEVCAPS command to determine whether the device instance sup¬ 
ports it. Repeated capture commands overwrite the image in the device element 
buffer. If the application wants to save the image, it can use the MCI_SAVE 
message or the MCI_GETIMAGEBUFFER message. The MCI_SAVE message 
will save the image to a file. The MCI_GETIMAGEBUFFER can be used to 
copy the image to the application’s buffer. If no rectangle is specified, then the 
entire video image in the video window is captured. 
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MCI_CLOSE 


MCI_CLOSE 

This message requests that the current media device instance be closed and all 
resources associated with it be freed. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR_SUCCESS MCIERR.DRIVER 

MCIERR_OUT_OF_MEMORY MCIERR_INVALID_FLAG 

MCIERR_INVALID_DEVICE_ID 
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MCI_CONNECTION 

MCLCONNECTION 

This message requests the ID of a connected device instance. An alias can also 
be assigned to the connected device instance to facilitate the sending of string 
commands to that device instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_QUERY_CONNECTION 

This flag specifies that the ID of the device instance connected to the cur¬ 
rent device instance is to be returned in the usToDevicelD field. 

MCI_CONNECTOR_TYPE 

This flag specifies that the connector type ( ulConnectorType field) for the 
primary device is to be used for the query. When this flag is used, the 
ulConnectorIndex field is used as a relative index rather than an absolute 
index. The following is the current list of connector types: 

• MCI_MIDI_STREAM_CONNECTOR 

• MCI_CD_STREAM_CONNECTOR 

• MCI_WAVE_STREAM_CONNECTOR 

• MCI_XA_STREAM_CONNECTOR 

• MCI_AMP_STREAM_CONNECTOR 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_MICROPHONE_CONNECTOR 

• MCI_LINE_IN_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 

• MCI_VIDEO_IN_CONNECTOR 

• MCI_VIDEO_OUT_CONNECTOR 

• MCI_UNIVERSAL_CONNECTOR 
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MC I_C ONNE C TOR_INDEX 

This flag specifies that the ulConnectorlndex field must contain the con¬ 
nector index for the primary device. If this flag is not specified, then an 
index of 1 is assumed. 

MCI_CONNECTOR_ALIAS 

This flag specifies that the pszAlias field contains an alias for the device 
instance connected to the specified connector. 

pParam2 (PMCI_CONNECTION_PARMS) —input 

A pointer to the MCI_CONNECTION_PARMS data structure. 


Returns 


MCIERR_SUCCESS 
MCIERR_INVALID_C ONNE CTION 
MCIERR_CANNOT_ADD_ALIAS 
MCIERR_DUPLICATE_ALIAS 
MCIERR_INVALID_DEVICE_ID 
MCIERR_INVALID_CONNECTOR_INDEX 
MCIERR_MISSING_FLAG 
MCIERR MISSING PARAMETER 


MCIERR_INVALID_DEVICE_ORDINAL 
MCIERR_UNSUPPORTED_FLAG 
MCIERR_UNSUPPORTED_CONN_TYPE 
MCIERR.INVALID CONNECTOR TYPE 


Remarks 


It is recommended that applications use the MCI_CONNECTOR_TYPE flag 
to shield them from the differences in vendor device connector numbering. 
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MCLCONNECTOR 


MCLCONNECTOR 

This message is used to enable, disable, or query the status of a particular con¬ 
nector for a device instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCIJENABLE_CONNECTOR 

Enables the specified connector. 

MCI_DISABLE_CONNECTOR 

Disables the specified connector. 

MCI_QUERY_CONNECTOR_STATUS 

Queries the status of the specified connector. The possible states are 
enabled or disabled. 

MCI__CONNECTOR_TYPE 

This flag specifies that the connector type (ulConnectorType field) for the 
primary device is to be used for the query. When this flag is used, the 
ulConnectorlndex field is used as a relative index rather than an absolute 
index. See MCI_CONNECTION for the list of possible connector types. 

MCI_CONNECTOR_INDEX 

This flag specifies that the ulConnectorlndex field contains the connector 
index for the primary device. If this flag is not specified, then an index of 
1 is assumed. 

pParam2 (PMCI_CONNECTOR_PARMS)—input 

A pointer to the MCI_CONNECTOR_PARMS data structure. 
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Returns 


MCBERR_SUCCESS 

MCIERR_INSTANCE_INACTIVE 

MCIERR_DRIVER 

MCIERR_IWALID_CONNECTION 

MCIERR_EWALID_DEVICE_ID 

MCIERR_MISSING_FLAG 

MCIEI®_INVAIJDD_DEVICE_ORDINAL 


MCIERR_UNSUPPORTED_FLAG 

MCIERR_UNSUPPORTED_CONN_TYPE 

MClERR_INVALID_CONNECTOR_TYPE 

MClERR_IIWAIJD_CONNECTOR_INDEX 

MCIERR_MISSING_PARAMETER 

MCIERR_CANNOT_MODIFY_CONNECTOR 


Remarks 


It is recommended that applications use the MCI_CONNECTOR_TYPE flag 
to shield them from the differences in vendor device connector numbering. 
Additionally, the MCI_CONNECTOR_INDEX flag can be used to address 
more than one connector of the same type. 

If only the MCI_CONNECTOR_INDEX flag is used, the referenced connector 
is device dependent. The connector type of a particular connector index, as well 
as the number of connectors, can be retrieved using the MCI_CONNECTOR- 
INFO message. 

The amplifier mixer device for the IBM M-Audio adapter does not have a head¬ 
phone connector. 

Disabling a connector on a device can terminate an active command. 
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MCLCONNECTORINFO 


MCLCONNECTORINFO 

This message is used to determine the total number of connectors on a device, 
the number of connectors of a specific type, the type of each connector, and 
whether or not a particular type of connection is valid for a given connector 
type. 


Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_CONNECTOR_TYPE 

This flag specifies that the connector type (ulConnectorType field) for the 
primary device is to be used for the query. When this flag is used, the 
ulConnectorlndex field is used as a relative index rather than an absolute 
index. See MCI_CONNECTION for the list of possible connector types. 

MCI_CONNECTOR_INDEX 

This flag specifies that the ulConnectorlndex field contains the connector 
index for the primary device. If this flag is not specified, then an index of 
1 is assumed. 

MCI_QUERY_CONNECTOR_TYPE 

This flag returns the connector type in the ulReturn Field. To specify the 
connector to query, use the MCI_CONNECTOR_INDEX flag. 

MCI_ENUMERATE_CONNECTORS 

This flag returns the number of connectors for the given device. If the 
MCI_CONNECTOR_TYPE flag is also specified, then the number of 
connectors of that type is returned. 

MCI_QUERY_VALID_CONNECTION 

This flag determines whether the specified connection is possible. 
MCI__TRUE is returned if the connection is possible, otherwise 
MCI_FALSE is returned. 
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MCI_TO_CONNECTOR_TYPE 

This flag specifies that the connector type (ulToConnectorType field) for 
the primary device is to be used for the query. When this flag is used, the 
ulToConnectorlndex field is used as a relative index rather than an 
absolute index. See MCI_CONNECTION for the list of possible connec¬ 
tor types. 

pParam2 (PMCI_CONNECTIONINFO_PARMS)—input 

A pointer to the MCI_CONNECTIONINFOJPARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_INVAIJD_DE\TCEJ3RDINAL 

MC1ERR_INVALID_DEVICE_TYPE 

MCIERR_MISSING_FLAG 

MCIERRJNVAIJD_FIAG 

MCIERR_UNSUPPORTED_FLAG 


MCTERRTNVAT ,TT)_C AT J ACKHANDT ,E 

MCIERR_INVAIID_CONNECTOR_TYPE 

MCIERR_INVAIJa3_CONNECTOR_INDEX 

MCIERR_MISSING_PARAMETER 

MCIERR_FLAGS_NOT_COMPATIBLE 


Remarks 


This message does not require a device instance to be open. The following is a 
list of connector types supported by each MMPM/2 device: 

Amplifier Mixer Device 

• MCI_AMP_STREAM_CONNECTOR 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_MICROPHONE_CONNECTOR 

• MCI_LINE_IN_CONNECTOR 

• MCI_LINE_0U1_C0NNECT0R 
CD Audio Device 

• MCI_CD_STREAM_CONNECTOR 

• MCI_HEADPHONES_CONNECTOR 
Sequencer Device 

• MCI_MIDI_STREAM_CONNECTOR 
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Waveform Audio Device 


• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 
Videodisc Device 

• MCI_LINE_OUT_CONNECTOR 

• MCI_VIDEO_OUT_CONNECTOR 
Digital Video Device 

• MCI_HEADPHONES_CONNECTOR 

• MCI_SPEAKERS_CONNECTOR 

• MCI_MICROPHONE_CONNECTOR 

• MCI_LINE_IN_CONNECTOR 

• MCI_LINE_OUT_CONNECTOR 

• MCI_VIDEO_IN_CONNECTOR 

• MCI_VIDEO_OUT_CONNECTOR 

The MCI_ENUMERATE_CONNECTORS, MCI_QUERY_CONNECTOR_ 
TYPE, and MCI_QUERY_VALID_CONNECTION flags are mutually exclu¬ 
sive. In addition, the MCI_ENUMERATE_CONNECTORS and MCI_CON- 
NECTOR_INDEX are also mutually exclusive. 
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MCI_COPY 


MCI_COPY 

This message copies the specified range of data from the device file to the clip¬ 
board or application buffer. The position of the media remains the same as 
before the copy message. 


Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI.FROM 

The beginning position of a copy from a file. 

MCI_TO 

The ending position of a copy from file. 

MCIJFROMJBUFFER 

The beginning position of a copy from an application supplied buffer. 

MCI_TO_BUFFER 

The ending position of a copy from an application supplied buffer. 
pParam2 (PMCI_EDIT_PARMS)—input 

A pointer to the MCX_EDIT_PARMS data structure. 

Returns 

MCIERR_SUCCESS MCIERR_INVALID_FLAG 

MCIERR_INVAIJD_BIJFFER MCIERR_UNSUPPORTED_FLAG 

MCIERR_OUTOFRANGE MCIERR_INSTANCE_INACTIVE 

MCIERR_MISSEVG_PARAMETER MCTERR JNVAT TD_C AT T R ACKHANDT E 

MCIERR_OlJT_OF_MEMORY MCIERR_CLIPBRD_ERR 
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Remarks 


This message copies the range of media data specified by the ulFrom and ulTo 
fields in the MCI_EDIT_PARMS data structure to an application-supplied 
buffer or the system clipboard. If the pBuff field of the data structure contains 
a pointer and the MCI_TO_BUFFER flag is specified, the data is copied to a 
buffer. If the MCI_FROM_BUFFER flag is specified, the information is 
copied from the buffer to the clipboard. 

The units of the MCI_FROM and MCI_TO parameters are interpreted in the 
currently selected time format. If neither the MCI_FROM nor MCI_TO is 
specified, the range is assumed from the current position to the end of the file. 
The difference between MCI_FROM and MCI_TO must be greater than zero, 
otherwise an error is returned. 

Edited AVI movie files cannot always be saved with their original name after a 
copy operation. If the clipboard contains a reference to data that would be 
erased during saving or if another instance of the digital video device has a 
pending paste operation which depends on this data, the file cannot be saved 
unless a new file name has been provided. If a new file name is not provided, 
MMIOERR_NEED_NEW_FILENAME is returned by the AVI MMIO 10 pro¬ 
cedure, and a temporary file is created to save the edited movie. The 
MCI_TO_BUFFER and MCI_FROM_BUFFER flags are not supported by 
the digital video device. 

If data is already in the clipboard, then it is overwritten. If a copy interrupts 
an in-progress operation, such as play, the operation is aborted, and a 
MM_MCINOTIFY message is sent to the application. 
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MCI_CUE 


MCLCUE 

This message prompts a device instance to preroll itself for a subsequent play¬ 
back or recording message with minimum delay. 


Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_CUE_INPUT 

This flag cues or prerolls the device instance for input or recording. 

MCI_CUE_OUTPUT 

This flag cues or prerolls the device instance for output or playback. 
Wave Audio Extensions 

The following flags apply to wave audio devices: 

MCI_WAVE_INPUT 

This flag cues or prerolls the device instance for input or recording. 

MCI_WAVE_OUTPUT 

This flag cues or prerolls the device instance for output or playback. 
pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_EWALID_DEVICE_ID 

MCIERR_EVSTANCE_ENACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVAL1D_CALLBACK_HANDLE 


MCIERRJHAEDWAKE 

MCIERR_FII^_NOT_FOUND 

MCIERR_UNSUPPORTED_FUNCTIONS 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 
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Remarks 

The flags MCI_CUE__INPUT (MCI_WAVE_INPUT) and MCI_CUE_OUT- 
PUT (MCI_WAVE_OUTPUT) are mutually exclusive. On devices that require 
a file, the file must be loaded before the MCI_CUE command is issued. Cueing 
for input is only supported on devices that support recording. 
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MCI_CUT 


MCI_CUT 

This message removes the specified range of data from the device element and 
places it in the system clipboard or application supplied buffer. 

Parameters 


ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCIJFROM 

This is the beginning position of a cut. The position of the media is either 
the position specified in the ulFrom field or the current position if 
MCI_FROM flag is not specified. 

MCI.TO 

The ending position of a cut operation. 

MCI.TOJBUFFER 

Places the data from a file into a application supplied buffer. If this flag is 
not specified, then the clipboard is used. 

pParam2 (PMCI_EDIT_PARMS)—input 

A pointer to the MCI_EDIT_PARMS data structure. 

Returns 


MCIERR_SUCCESS 

MCIERR_INVALID_BUFFER 

MCIERR_CANNOT_WRITE 

MCIERR_OUTOFRANGE 

MCIERR_INVALID_DEVICE_ID 

MCIERR_OUT_OF_MEMORY 


MCIERR_MISSING_PARAMETER 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INSTANCE_INACTIVE 

MCIERR_INVALID_CALLBACK_HANDLE 

MMIOERR_CLIPBRD_ERR 
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Remarks 

If MCI_TO.BUFFER is specified and the buffer size is not large enough to 
hold the data then the error MCIERR_INVALID_BUFFER is returned. 

The units of the from and to parameters are interpreted in the currently select¬ 
ed time format. If neither the MCI.FROM nor MCI.TO is specified, the range 
is assumed from the current position to the end of the file. The difference 
between from and to must be greater than zero, otherwise an error is returned. 

Edited AVI movie files cannot always be saved with their original name after a 
copy operation. If the clipboard contains a reference to data that would be 
erased during saving or if another instance of the digital video device has a 
pending paste operation which depends on this data, the file cannot be saved 
unless a new file name has been provided. If a new file name is not provided, 
MMIOERR_NEED_NEW_FILENAME is returned by the AVI MMIO 10 pro¬ 
cedure and a temporary file is created to save the edited movie. The 
MCI_TO_BUFFER and MCI_FROM_BUFFER flags are not supported by 
the digital video device. 

If data is already in the clipboard, then it is overwritten. If a cut interrupts an 
in-progress operation, such as play, the operation is aborted and a 
MM.MCINOTIFY message is sent to the application. 

Wave Audio Specific 

If either the from or to positions begin in the middle of a digital audio sample, 
the wave audio data begins at the beginning of that sample. If 
MCI_FROM_BUFFER or MCI_TO_BUFFER are used, the pHeader field of 
the MCI_EDIT_PARMS data structure must contain a pointer to an MMAU- 
DIOHEADER structure. The ulBufLen field of MCI.EDIT.PARMS must be 
filled in. 
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MCI__DEFAULT_CONNECTION 


MCI_DEFAULT_CONNECTION 

This message is used to make, break, and query default connections between 
devices. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_QUERY_CONNECTION 

This flag specifies that the default connection associated with the indicat¬ 
ed connector is to be returned in the pszToDevice, ulToConnectorType, 
and ulToConnectorlndex fields of the MCI_DEFAULT_CONNEC- 
TION_PARMS data structure. 

MCI_MAKE_CONNECTION 

This flag specifies that a default connection is to be established between 
the current device instance and the device ID specified by the 
ulDeviceTypelD field of the MCI_DEFAULT_CONNECTION_PARMS 
data structure. 

MCI_BREAK_CONNECTION 

This flag specifies that the default connection associated with the indicat¬ 
ed connectors is to be broken. 

MCI_CONNECTOR_TYPE 

This flag specifies that the connector type ( ulConnectorType field) for the 
primary device is to be used for the query. When this flag is used then the 
ulConnectorlndex field is used as a relative index rather than an absolute 
index. See MCI_CONNECTION for the list of possible connector types. 

MCI_CONNECTOR_INDEX 

This flag specifies that the ulConnectorlndex field contains the connector 
index for the primary device. If this flag is not specified than an index of 1 
is assumed. 
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MCI_TO_CONNECTOR_TYPE 

This flag specifies that the connector type (ulToConnectorType field) for 
the primary device is to be used for the query. When this flag is used then 
the ulToConnectorlndex field is used as a relative index rather than an 
absolute index. See MCI_CONNECTION for the list of possible connec¬ 
tor types. 

MCI_TO_CONNECTOR_INDEX 

This flag specifies that the ulToConnectorlndex field contains the connec¬ 
tor index for the primary device. If this flag is not specified, then an index 
of 1 is assumed. 

pParam2 (PMCI_DEFAULT_CONNECTION_PARMS)—input 

A pointer to the MCIJDEFAULT_CONNECTION_PARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_INVALID_CAT J ACK_HANDLE 

MCIERR_INSTANCE_INACTIVE 

MCIERR_DRIVER 

MCIERR_EWALJD_CONNECTION 

MCIERR_INVAIJT)_DE\TCE_ORDIN^ 

MCIERR_I]WALID_DEVICE_ID 

MCIERR_MISSING_FLAG 


MCIERR_UNSUPPORTED_FLAG 

MCIERR_UNSUPPORTED_CONN_TYPE 

MCIERR_INVALID_CONNECTOR_TYPE 

MCIERR_INVALJD_CO]SONECTOR_INDEX 

MCIERR_MISSING_PARAMETER 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_NO_CONNECTION 



APPENDIX A: Media Control Interface 417 


MCI_DELETE 


MCI_DELETE 

This message removes the specified range of data from the device file. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI.FROM 

The beginning position of a delete. The position of the media is either the 
position specified in the ulFrom field or the current position if 
MCI_FROM is not specified. 

MCI.TO 

The ending position of a delete operation. 
pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR.SUCCESS 

MdERR_CANNOT_WRTTE 

MCIERR.OUTOFRANGE 

MCIERR_INVALID_DEVICE_ro 

MCIERR_MISSING_PARAMETER 


MCIERR_INVALro_FLAG 
MCIERR_UNSUPPORTED_FLAG 
MCIERR_INSTANCE_rNACTIVE 
MCIERR_Ds[VALID_CAT J JTACKJHANDLE 
MCIERR_OUT_OF_MEMORY 


Remarks 


The units of the MCI_FROM and MCI_TO parameters are interpreted in the 
currently selected time format. If neither the MCI_FROM nor MCI_TO is 
specified, the range is assumed from the current position to the end of the file. 
The difference between MCI_FROM and MCI_TO must be greater than zero, 
otherwise an error is returned. 

The from and to parameters are interpreted in the following manner. They are 
numbered starting from 0. The from is assumed to be inclusive and the to is 
assumed to be exclusive. For example, if a delete for samples 100 through 150 
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is specified, then the from would be 100 and the to would be 151. The position 
after the delete would be at sample 100. 

Edited AVI movie files cannot always be saved with their original name after a 
copy operation. If the clipboard contains a reference to data that would be 
erased during saving or if another instance of the digital video device has a 
pending paste operation which depends on this data, the file cannot be saved 
unless a new file name has been provided. If a new file name is not provided, 
MMIOERR_NEED_NEW_FILENAME is returned by the AVI MMIO 10 pro¬ 
cedure and a temporary file is created to save the edited movie. The 
MCI_TO_BUFFER and MCI_FROM_BUFFER flags are not supported by 
the digital video device. 
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MCI_DEVICESETTI NGS 


MCLDEVICESETTINGS 

This message is sent to a Media Control Interface driver (MCD) when the 
Multimedia Setup application is inserting pages into the MMPM/2 Setup note¬ 
book. This message provides the MCD the opportunity to insert custom set¬ 
tings pages. 


Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_DEVICESETTINGS_PARMS)—input 

A pointer to the MCI_DEVICESETTINGS_PARMS data structure. 


Returns 


Return code contains the handle to a settings page or zero if no page is 
inserted. 

Remarks 

The MCI_NOTIFY flag is not valid for this message. 

This message is sent only if the MCI_SYSINFO_DE VICE SETTINGS flag is 
set in the ulDeviceFlag field of the MCI_SYSINFO_LOGDEVTCE data struc¬ 
ture for the logical device definition. This command does not require the device 
to be opened. This command is used mainly by the Multimedia Setup applica¬ 
tion and should not be used for general purpose MMPM/2 applications. 
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MCI_ESCAPE 


MCI_ESCAPE 

This message sends messages directly to the Vendor Specific Driver or the 
Device Driver. This message is not interpreted by the Media Control Interface 
Driver and is passed directly through. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_ESCAPE_STRING 

This flag indicates a command string is specified in the pszCommand 
field of the MCI_ESCAPE_PARMS data structure. 

pParam2 (PMCI_ESCAPE_PARMS)—input 

A pointer to the MCI_ESCAPE_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MClERR_INVALro_DEVICE_ID 

MCIERR_INSTANCE_INACTTVE 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MC1ERR_INVALID_CAI J JIACKJ3ANDLE 


MCIERR.HARDWARE 

MCIERR_UNSUPPORTED_FUNCTION 

MC1ERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATlBLE 

MCIERR_MISSING_PARAMETER 


Remarks 

This message is not supported by any known devices in release 1.1 or Warp of 
MMPM/2. The message provides a means of passing a command string directly 
to a VSD or device driver for execution. 
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MCIJ=REEZE 


MCIJREEZE 

This message freezes the motion video on an area of the display. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 


Video Overlay Extensions 

MCI_OVLY_FREEZE_RECT 

Specifies that the rc field of the MCI_OVLY_RECT_PARMS data struc¬ 
ture contains a valid rectangle. If this flag is not specified, then the entire 
image is frozen. 

mci_ovly_freeze_rect_outside 

Specifies that the area outside the specified rectangle is to be affected. If 
this flag is not specified, then the area inside is affected. This flag must 
be specified with the MCI_OVLY_FREEZE_RECT flag. 

pParam2 (PMCI_OVLY_RECT_PARMS)—input 

A pointer to the MCI_OVLY_RECT_PARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICEJD 

MCIERR_MISSING_PARAMETER 

MCIERR.DRIVER 


MCIERR_INVALID_FLAG 

MCIERR_INSTANCE_INACTIVE 

MCIERR_OVLY_INVALID_RECT 

MCIERR_OVLY_NOT_AVAILABLE 
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Remarks 

MCI.FREEZE differs from MCI_PAUSE because MCI.FREEZE causes 
video overlay devices to cease updating the video image without affecting the 
state of the image source device (external video device). 

Multiple freeze and unfreeze commands, which specify rectangles to be affect¬ 
ed, can be issued sequentially to build up a complex region of frozen and 
unfrozen videos. 
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MCI_GETDEVCAPS 


MCI_GETDEVCAPS 

This message is used to return static information about the capabilities of a 
particular device instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_GETDEVCAPS_EXTENDED 

Indicates extended device capabilities are required. See the individual 
device specific extensions for each device for use of this flag. 

MCI_GETDEVCAPS_MESSAGE 

The usMessage field of the MCI_GETDEVCAPS_PARMS data structure 
contains a constant specifying the message to be queried. If the device 
supports that message then MCI_TRUE is returned, otherwise 
MCI_FALSE is returned. 

MCI_GETDEVCAPS_ITEM 

The ulltem field of the MCI_GETDEVCAPS_PARM data structure con¬ 
tains a constant specifying the device capability to be queried. The follow¬ 
ing list of items can be used regardless of the type of device. 

MCI_GETDEVCAPS_CAN_EJECT 

Returns MCI_TRUE if the device (for example a CD device) can eject its 
media; otherwise it returns MCI_FALSE. 

MCI_GETDEVCAPS_CAN_LOCKEJECT 

Returns MCI_TRUE if the device can disable the manual ejection of its 
media; otherwise, it returns MCI_FALSE. 

MCI_GETDEVCAPS_CAN_PLAY 

Returns MCI_TRUE if the device can play its media; otherwise it returns 

MCI.FALSE. 
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MCI_GETDEVCAPS_CAN_PROCESS_INTERNAL 

Returns MCI_TRUE if the device can internally process digital data such 
as CD Digital Audio drive with a build in digital to analog converter 
(DAC); otherwise it returns MCI_FALSE. 

mci_getdevcaps_can_record 

Returns MCX_TRUE if the device can record its media; otherwise, it 
returns MCI_FALSE. 

MCX_GETDEVCAPS_CAN_RECORD_INSERT 

Returns MCI_TRUE if the device supports the insertion of data during 
record; otherwise, it returns MCI_FALSE. The default recording mode is 
overwriting of the data to the media. 

MCX_GETDEVCAPS_CAN_SAVE 

Returns MCI_TRUE if the device can save files; otherwise, it returns 

MCI.FALSE. 

MCI_GETDEVCAPS_CAN_SET_VOLUME 

Returns MCI_TRUE if the device can change the audio volume level; oth¬ 
erwise, it returns MCI_FALSE. 

MCX_GETDEVCAPS_CAN_STREAM 

Returns MCI_TRUE if the device can stream digital data continuously to 
or from memory; otherwise, it returns MCX_FALSE. 

MCI_GETDEVCAPS_DEVICE_TYPE 

Returns the constant defined for this particular device type. 

MCI_GETDEVCAPS_HAS_AUDIO 

Returns MCI_TRUE if the device is capable of playing audio; otherwise, 
it returns MCI_FALSE. 

MCI_GETDEVCAPS_HAS_IMAGE 

Returns MCX_TRUE if the device supports a still image in its device 
instance; otherwise, it returns MCI_FALSE. 

MCX_GETDEVCAPS_HAS_VIDEO 

Returns MCI_TRUE if the device is capable of playing video; otherwise, 
it returns MCI_FALSE. 
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MCI_GETDEVCAPS_PREROLL_TIME 

Returns a deterministic or maximum notified preroll time in MMTIME 
units. A value of 0 indicates that an upper boundary to the preroll time is 
not known. 

MCI_GETDEVCAPS_PREROLL_TYPE 
Returns MCI_PREROLL_NONE. 

MCI_GETDEVCAPS_USES_FILES 

Returns MCI_TRUE if the device requires a file or play list pointer; oth¬ 
erwise, it returns MCI_FALSE. 

Waveform Audio Extensions 

If the MCI_GETDEVCAPS_EXTENDED flag is specified in conjunction with 
the MCI_GETDEVCAPS_ITEM flag, the following flags can be placed in the 
ulltem field for the waveaudio device: 

MCI_GETDEVCAPS_WAVE_FORMAT 

This flag allows an application to determine whether a specific waveaudio 
format is supported. The application must fill in the ulBitsPerSample , 
ulFormatTag , ulSamplePerSec , ulChannels, and ulFormatMode fields in 
the MCI_WAVE_GETDEVCAPS_PARMS data structure. If the format 
is supported, the driver returns MCI_TRUE. If the format is not support¬ 
ed, the driver returns a return code that indicates why the command 
failed. 

Videodisc Extensions 

MCI_VD_GETDEVCAPS_CAN_REVERSE 

Returns MCI_TRUE if the videodisc player can play in reverse; other¬ 
wise, it returns MCI_FALSE. Some players can play CLV discs in 
reverse as well as CAV discs. 

MCI_VD_GETDEVCAPS_FAST_RATE 

Returns the standard fast play rate in the current speed format, either as 
a percentage or in frames per second. 

MCI_VD_GETDEVCAPS_SLOW_RATE 

Returns the standard slow play rate in the current speed format, either 
as a percentage or in frames per second. 
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MCI_VD_GETDEVCAPS_NORMAL_RATE 

Returns the normal rate of play in frames per second. 

MCI_VD_GETDEVCAPS_MAXIMUM_RATE 

Returns the maximum play rate in the current speed format, either as a 
percentage or in frames per second. 

MCI_VD_GETDEVCAPS_MINIMUM_RATE 

Returns the minimum play rate in the current speed format, either as a 
percentage or in frames per second. 

MCI_VD_GETDEVCAPS_CLV 

Specifies that the requested capability information is relative to CLV for¬ 
matted discs. 

MCI_VD_GETDEVCAPS_CAV 

Specifies that the requested capability information is relative to CAV for¬ 
matted discs. This is the default. 

Digital Video Extensions 

MCI_DGV_GETDEVCAPS_CAN_DISTORT 

Returns MCI_TRUE if the device can distort the image independently in 
horizontal and vertical dimensions; otherwise, it returns MCI_FALSE. 

mci_dgv_getdevcaps_can_reverse 

Returns MCI_TRUE if the device can play in reverse; otherwise, it 
returns MCI_FALSE. 

MCI_DGV_GETDEVCAPS_CAN_STRETCH 

Returns MCI_TRUE if the device can stretch the image to fill the frame; 
otherwise, it returns MCI_FALSE. 

MCI_DGV_GETDEVCAPS_FAST_RATE 

Returns the standard fast playback rate (twice the recorded playback 
rate) in the current speed format, either as a percentage or in frames per 
second. Returns the normal play rate if the device cannot play fast. 

MCI_DGV_GETDEVCAPS_SLOW_RATE 

Returns the standard slow playback rate (half the recorded playback rate) 
in the current speed format, either as a percentage or in frames per sec¬ 
ond. Returns the normal play rate if the device cannot play fast. 
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MCI_DGV__GETDEVCAPS_NORMAL_RATE 

Returns the recorded play back rate in the current speed format, either as 
a percentage or in frames per second. 

MCI__DGV_GETDEVCAPS_VIDEO_X_EXTENT 

Returns the nominal horizontal (X) extent of the digital motion video 
image. 

MCI_DGV_GETDEVCAPS_VIDEO_Y_EXTENT 

Returns the nominal vertical (Y) extent of the digital motion video image. 

MCI_DGV_GETDEVCAPSJMAGE_X_EXTENT 

Returns the nominal horizontal (X) extent of images, if applicable. 

MCI_DGV_GETDEVCAPS_IMAGE_Y_EXTENT 

Returns the nominal vertical (Y) extent of images, if applicable. 

MCI_DGV_GETDEVCAPS_OVERLAY_GRAPHICS 

Returns MCI_TRUE if the device supports overlaying video with applica¬ 
tion generated graphics; otherwise, it returns MCI_FALSE. 


Video Overlay Extensions 

MCI_OVLY_GETDEVCAPS_CAN_DISTORT 

Returns MCI_TRUE if the device can distort the image independently in 
horizontal and vertical dimensions; otherwise, it returns MCI_FALSE. 

MCI_OVLY_GETDEVCAPS_CAN_FREEZE 

Returns MCI_TRUE if the device can freeze the image; otherwise, it 
returns MCI_FALSE. 

MCI_OVLY_GETDEVCAPS_CAN_STRETCH 

Returns MCI_TRUE if the device can stretch or shrink the image to fill 
the frame; otherwise, it returns MCI_FALSE. 

MCI_OVLY_GETDEVCAPS_VIDEO_X_EXTENT 

Returns the nominal horizontal (X) extent of the video source (706 for 
both NTSC and PAL video). 

MCI_OVLY_GETDEVCAPS_VIDEO_Y_EXTENT 

Returns the nominal vertical (Y) extent of the video source (484 for NTSC 
and 564 for PAL video). 
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MCI_OVLY_GETDEVCAPS_IMAGE_X_EXTENT 

Returns the nominal horizontal (X) extent of images, if applicable. 

MCI_OVLY_GETDEVCAPS_IMAGE_Y_EXTENT 

Returns the nominal vertical (Y) extent of images, if applicable. 

MCI_OVLY_GETDEVCAPS_OVERLAY_GRAPHICS 

Returns MCI_TRUE if the device supports overlaying video with applica¬ 
tion generated graphics; otherwise, it returns MCI_FALSE. 

MCI_OVLY_GETDEVCAPS_MAX_WINDOWS 

Returns the maximum number of window that the device can handle con¬ 
currently. 

pParam2 (PMCI_GETDEVCAPS_PARMS)—input 

A pointer to the MCI_GETDEVCAPS_PARM data structure. 

Returns 


MCIERR_SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_EWALID_DEVICE_n> 

MCIERR_MISSING_PARAMETER 

MCIERRJDRIVER 

MCIERR_INVALID_FLAG 

MCIERR_MISSING_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 


MClERR_INVALID_rrEM 

MCIERR_UNSUPP_SAMPLESPERSEC 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_UNSUPP_BITSPERSAMPLE 

MCIERR_UNSUPP_CHANNELS 

MCIERR_UNSUPP_FORMAT_MODE 

MCIERR_UNSlJPP_FORMAT_TAG 


Remarks 


The flags MCI_GETDEVCAPS_ITEM and MCI_GETDEVCAPS_MES- 
SAGE are mutually exclusive. In release 1.1 of MMPM/2 the following flags 
are not supported: MCI_DGV_GETDEVCAPS_MINIMUM_RATE, 
MCI_DGV_GETDEVCAPS_MAXIMUM_RATE, and MCI_DGV_GETDEV- 
C APS_MAX_WINDO W S. 

The values for video extent specify the largest video image that can be cap¬ 
tured and thereby define the extents of the video capture coordinate system. 
Capture regions specified by the MCI_PUT message must lie entirely within 
these extents. 

The values for image extent specify the largest still image that can be captured 
with the device. Although the MCI_CAPTURE message is not supported by 
the digital video device, the values returned are the same as video extents for 
supported hardware. 
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MCI_GETIMAGEBUFFER 


MCLGETIMAGEBUFFER 

This message returns the data in the element buffer that was captured with 
the MCI_CAPTURE command, obtained by the MCIJLOAD command, or 
provided by the MCI_SETIMAGEBUFFER command. The image data is 
returned in the device specific format, unless MCI_CONVERT is specified, in 
which case the data is returned in OS/2 bitmap format. The current values for 
PELFORMAT and BITSPERPEL will be used if possible. The data will be 
uncompressed. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_CONVERT 

Specifies that the image format will be converted to the OS/2 bitmap for¬ 
mat. The default is the device specific format. 

MCI_USE_HW_BUFFER 

Indicates that the hardware buffer contains the image data. This causes a 
capture to be performed automatically. 

MCI_GET_HW_BUFFER_PTR 

Requests a pointer to the hardware buffer. This flag is not supported by 
the digital video device. 

Video Overlay Extensions 

MCI_QUERY_IMAGEJBUFFER 

This flag specifies that the information about the buffer is to be returned 
in the MCI_IMAGE_PARMS structure. No buffer is actually obtained. 
The length of the buffer is placed in the ulBufLen field. The width and 
height of the buffer (in pels) are placed in the red field. The rectangle 
might be different for standard and device-specific formats, which might 
not be identical to the rectangle provided in the capture command. The 
PELFORMAT and BITSPERPEL values in the buffer are placed in the 
ulPelFormat and ulBitCount fields respectively. Values returned are 
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dependent upon the value set for the MCI_CONVERT flag. If 
MCI_CONVERT is TRUE, the buffer length and rectangle are that 
required must contain the device-specific version. If FALSE, the length 
and rectangle represent that required must contain an OS/2 memory 
bitmap version. 

pParam2 (PMCI_IMAGE_PARMS)—input 

A pointer to the MCI_IMAGE_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR.DRIVER 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INSTANCE_INACTIVE 

MCIERR_INVALIDJBUFFER 

mcierr_ovly_empty_buffer 

MCIERR_FILE_NOT_FOUND 

MCIERR_TARGET_DEVICE_FULL 


Remarks 


This command might not be supported by the digital video device. To deter¬ 
mine whether the device supports the command, issue an MCI_GETDEV- 
CAPS query. 

The format of the image data returned is specified by the ulPelFormat and 
usBitCount fields of the data structure pointed to by pParam2 (if possible), 
unless MCI_CONVERT is specified, in which case the data is returned in 
OS/2 memory bitmap format. The beginning of the buffer contains the 
BITMAPINFOHEADER2 data, followed by the palette (if any) and the pel 
data. 

On dual-plane image capture hardware devices, the image layer content is 
assumed. Only visible data can be captured with some hardware, particularly 
single-plane devices. The image data returned will be uncompressed, in either 
OS/2 memory bitmap format or device-specific format, based on the setting of 

the MCI.CONVERT flag. 

The current setting for the IMAGE BITSPERPEL and IMAGE PELFORMAT 
will be used if supported by the device. The IMAGE FILEFORMAT and 
IMAGE COMPRESSION settings will be ignored. 

Conversion from internal YUVB format to OS/2 bitmap format is accomplished 
with an I/O procedure which can use disk space for temporary storage. 
Therefore, it is possible that errors such as MCIERR_TARGET_ 
DEVICE_FULL (no disk space) can occur. 
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MCI_GETIMAGEPALETTE 


MCLGETIMAGEPALETTE 

This message returns the current palette or color map for the currently cap¬ 
tured image, if one is available. 


Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_FIND_BEST_REGISTERED 

Select the best palette from the registered color maps and return its ID in 
the usRegisteredMap field of the MCI_PALETTE_PARMS data 
structure. 

mci_query_registered_map 

This flag specifies that the palette specified in the usRegisteredMap field 
is to be returned in the array specified in the pPalette field. The size of the 
palette is returned in the ulPalEntries field. 

MCI_QUERY_REGISTERED_MAP_SIZE 

This flag specifies that the size of the palette in the usRegisteredMap field 
is to be returned in the ulPalEntries field. This can be used to determine 
the size of the array to use for MCI_QUERY_REGISTERED_MAP. 

pParam2 (PMCI_PALETTE_PARMS)—input 

A pointer to the MCI_PALETTE_PARMS data structure. 


Returns 


MCIERR_SUCCESS MCIERRJNVALID_FLAG 

MCIERR_INVALID_DEVICE_ID MCIERR_FLAGS_NOT_COMPAITBIJE 

MCIERR_DEVICE_LOCKED MCIERR_INVAIJD_CAIJLBACK_HANDLE 
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Remarks 

This command might not be supported by the digital video device. To deter¬ 
mine whether the device supports the command, issue MCI_GETDEVCAPS. 

On dual-layer image capture hardware devices, the image layer content is 
assumed. The computation of the palette is based only on visible data on some 
hardware, particularly single-plane devices. 
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MCI_GETTOC 


MCLGETTOC 

This message returns a table of contents structure for the currently loaded 
Compact Disc. 

Parameters 

ulParaml (ULONG)—input 
pParam2 (PMCI_TOC_PARMS)—input 

A pointer to the MCI_TOC__PARMS data structure. 


Returns 


MCIERR.SUCCESS MCIERR_INVAIJD_FLAG 

MCIERR_INVALrD_DEVICE_ID MCIERR_FIAGS_NOT_COMPATTBLE 

MCIERR_INSTANCE_INACTIVE MCIERR_INVALID_BUFFER 

MCIERR_UNSUPPORTED_FLAG MCIERR_MISSING_PARAMETER 

MCIERR_INVALID_CATJ,BACK_HANDLE MCIERR_DEVICE_NOT_READY 
MCIERR_UNSUPPORTED_FUNCTION 


Remarks 


Device and table of contents structure for the currently loaded disc is returned 
in the MCI_TOC_REC data structure. From this point, the controlling pro¬ 
gram can select the CD audio object (audio track in this case) to play. If the 
size of the buffer passed through is too small to hold all the data returned, then 
the ulBufSize field contains the required buffer size, the error code 
MCIERR_INVALID_BUFFER is returned, and the buffer contains only as 
much of the GETTOC data as its size permits. 

Note: Not all CD-ROM drives capable of playing digital-audio compact discs 
support this feature. 
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MCI_GROUP 


MCI_GROUP 

This message allows applications to create and delete groups of device 
instances. Group commands allow applications to control several devices using 
a single command. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_GROUP_MAKE 

This flag specifies the creation of a group. An array of device Ids is provid¬ 
ed by the application in the paulDevicelD field of the 
MCI_GROUP_PARMS data structure. The number of these Ids is pro¬ 
vided by the application in the ulNumDevices field. If one or more device 
Ids are invalid then the error MCIERR_INVALID_DEVICE_ID is 
returned. If a device ID is already in another group, the 
MCIERR_ID_ALREADY_XN_GROUP error message is returned. 

MCI_GROUP_DELETE 

This flag deletes an existing group. None of the device instances in the 
group is closed only the group reference is deleted. 

MCI_GROUP_ALIAS 

This flag specifies that the pszGroupAlias field contains an alias for the 
group. This flag is valid on with MCI_GROUP_MAKE. The given alias 
can then be used to refer to the group (from the string interface). If the 
alias is already in use, then the error MCIERR_DUPLICATE_ALIAS 
error is returned. 

MCI_GROUP_NOPIECEMEAL 

This flag specifies that the group is to be treated as a whole entity rather 
than a group of separate parts. This ensures that if one or more device 
instances in the group becomes inactive, then all the device instances in 
the group become inactive. This flag is only valid with the 
MCI_GROUP_MAKE flag. If, upon the creation of a group with the 
nopiecemeal flag, one or more of the device instances is already inactive, 
then all the device instance will be made inactive. 
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pParam2 (PMCI_GROUP_PARMS)—input 

A pointer to the MCI_GROUP_PARMS data structure. 


Returns 


MCIERR_SUCCESS MCIERR_ID_ALREADY_IN_GROUP 

MCIERR_DUPLICATE_ALIAS MCIERR_INVALID_GROUP_ID 

MCIERR_FLAGS_NOT_COMPATIBLE 


Remarks 


Once a group is created, certain messages sent to the group’s ID (or alias 
name) are in turn sent to each device making up that group. The following is a 
list of all the valid messages that can be sent to a group: 

MCI.ACQUIREDEVICE MCIJPLAY MCI.SEEK 

MCI_CUE MCI.RECORD MCI_SET 

MCI.CLOSE MCI.RELEASEDEVICE MCI_STOP 

MCI_PAUSE MCI_RESUME 
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MCIJNFO 


MCIJNFO 

This message returns string information from a media device instance. This 
information does not describe the capabilities of the device, just static informa¬ 
tion about the device. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_INFO_PRODUCT 

This flag returns a product name or description of the particular hard¬ 
ware associated with a device. 

CD Audio Extensions 

MCI_CD_INFO_ID 

This flag returns the disc ID (8 bytes) consisting of the starting address, 
ending track number, and address of the lead out track. The disc ID is 
generated by the CD Audio Media Control Device and is not necessarily 
unique. 

MCI_CD_INFO_UPC 

This flag returns the disc’s UPC code (serial number) if the device sup¬ 
ports this function; otherwise it returns 0. The UPC is BCD coded. Not all 
discs have UPCs. 

Videodisc Extensions 

MCI_VD_INFO_LABEL 

This flag returns the videodisc label. 

Wave Audio Extension 

MCI_INFO_FILE 

This flag returns the file name of the current file. 
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Sequencer Audio Extension 


MCI_INFO_FILE 

This flag returns the file name of the current file. 


Digital Video Extension 

MCI_DGV_INFO_VIDEO_FILE 

This flag returns the file name of the current file. 

MCI_DGV_INFO_IMAGE_FILE 

This flag returns the file name of the current image file used by the 
device. 

MCI_DGV_INFO_TEXT 

This flag returns the caption of the window in which the digital video is 
currently displayed. 


Video Overlay Extension 

MCI_INFO_FILE 

This flag returns the file name of the current file. 

MCI_OVLY_INFO_TEXT 

This flag returns the caption of the window in which the video overlay is 
currently displayed. 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_I]WALID_CALLBACK_HANDLE 

MCIERR_INVALID_FLAG 

MdERR_FLAGS_NOT_COMPATTBLE 

MCIERR_EWALID_BUFFER 

MCIERR_MISSING_PARAMETER 
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Remarks 


The parameters and flags for this message vary according to the selected 
device. If the size of the buffer passed through is too small to hold all the data 
returned, ulRetSize will contain the required buffer size, the error code 
MCXERR_INVALID_BUFFER will be returned, and the buffer will only con¬ 
tain as much of the INFO data as its size permits. Only one flag can be used 
per MCIJNFO message; otherwise the error, MCIERR_FLAGS_NOT_COM- 
PATIBLE, is returned. 
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MCI_LOAD 


MCI_LOAD 

This message is used for specifying a new file to be load onto an already open 
device instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_OPEN_ELEMENT 

This flag specifies that an element name is included. The element name 
can be that of a file or a file element in a compound file. If the element 
name does not exist or is NULL, then a temporary element is created for 
subsequent use (recording). The temporary file can be made permanent 
by providing a name using the MCI_SAVE message. 

MCI_OPEN_MMIO 

This flag specifies that a MMIO handle ( hmmio) is passed in the 
pszElementName field of the open data structure. The file must have been 
opened through MMIO with the ulTranslate field set to MMIO_TRANS- 
LATEHEADER, unless a particular Media Control Device indicates 
differently. 

M[CI_READONLY 

This flag specifies that the file is to be opened in read-only mode. This can 
improve the performance of the load for wave audio and digital video 
devices. This flag can only be used in conjunction with the 
MCI.OPENJELEMENT flag. By specifying this flag MCIJRECORD 
and MCI_SAVE are disabled. 

Video Overlay Extensions 

The image contained in the file is loaded into the image device element and 
overwrites any images currently stored there. It can be displayed using the 

MCI_RESTORE command. 

The file is opened, accessed, and closed on this command. If the format of the 
image file is not recognized as either a device specific file format or a format 
supported by MMIO the load fails. 
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Load performs an automatic set of the following values for: 

IMAGE BITSPERPEL 
IMAGE PELFORMAT 
IMAGE COMPRESSION 
IMAGE QUALITY 
IMAGE EXTENTS 

M-Motion Overlay implementation values would be: 

IMAGE BITSPERPEL = 21 
IMAGE PELFORMAT = yuvb 
IMAGE COMPRESSION = BI_NONE 
IMAGE QUALITY = photo 
IMAGE EXTENTS = image specific 

The previous values for these attributes are ignored. Load also automatically 
sets IMAGE_FILEFORMAT to indicate information about the original file. 

pParam2 (PMCI_LOAD_PARMS)—input 

A pointer to the MCI_LOAD_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MC1ERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR_DRIVER 

MCIERRJNVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_INSTANCE_INACTIVE 

MCIERR_FILE_NOT_FOlJND 


MCIERR_INVALID_MEDIA_TYPE 

MCIERR_HARDWARE 

MCIERR_FILE_ATTRIBUTE 

MCIERR_UNSUPP_SAMPLESPERSEC 

MCIERRJJNSUPPJBITSPERSAMPLE 

MCIERR_UNSUPP_CHANNELS 

MCIERR_UNSUPP_FORMAT_MODE 

MCIERR_UNSUPP_FORMAT_TAG 


Remarks 


When an existing media element is loaded into a device, the settings for the 
device will change if they are overridden by the settings required by the media 
element. If a new media element is created by loading a non-existent media 
element, the new media element should be created with default settings for the 
particular device. 

The flags MCI_OPEN_ELEMENT and MCI_OPEN_MMIO are mutually 
exclusive. 
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MCI_MASTERAUDIO 


MCLMASTERAUDIO 

This message provides support for setting and retrieving system wide audio 
control settings. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_QUERYCURRENTSETTING 

This flag queries the current state of the indicated audio attribute. 

MCI.QUERYSAVEDSETTING 

This flag queries the saved state of the indicated audio attributed. 

MCI_S AVE SETTIN G 

This flag saves the current setting of the indicated audio attribute. 

MCIJVLASTERVOL 

System master volume level as a percentage. If a number greater than 
100 is given then 100 will be used as the master volume setting. 

MCI.SPEAKERS 

This flag sets the output to speakers. 

MCI.HEADPHONES 

This flag sets the output to headphones. 

MCI.ON 

This flag sets the output on or enabled. This must be used in conjunction 
with the MCI.SPEAKERS or MCI.HEADPHONES flag. 

MCI.OFF 

This flag sets the output off or disabled. This must be used in conjunction 
with the MCI_SPEAKERS or MCIJHEADPHONES flag. 

pParam2 (PMCI_MASTERAUDIO_PARMS)—input 

A pointer to the MCI_MASTERAUDIO_PARMS data structure. 
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Returns 


MCIERRJ3UCCESS 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INVALID_FLAG 
MCIERR_FLAGS_N OT_C OMP ATIBLE 
MCIERR_MISSING_PARAMETER 


Remarks 


The MCI_NOTIFY flag is not valid for this message. 

Two levels of volume control are provided: system wide and device-context spe¬ 
cific. The MCIJ3ET command affects only one specific device opened by an 
application, but the MCI_MASTERAUDIO command affects all open logical 
devices in the system. 
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MCI_OPEN 


MCLOPEN 

This message is used to open or create a new device instance or instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_OPEN_SHAREABLE 

This flag specifies that the device instance is to be open in a fully share¬ 
able mode. 

MCI.OPENJELEMENT 

This flag specifies that an element name is included. The element name 
can be that of a file or a file element in a compound file. If the element 
name does not exist or is NULL, then a temporary element is created for 
subsequent use (recording). The temporary file can be made permanent 
by providing a name using the MCI_SAVE message. 

MCI_OPEN_MMIO 

This flag specifies that a MMIO handle (hmmio) is passed in the 
pszElementName field of the open data structure. The file must be opened 
through MMIO with the ulTranslate field set to MMIO_TRANSLATE- 
HEADER unless a particular Media Control Device indicates differently. 

MCIJREADONLY 

This flag specifies that the file is to be opened in read-only mode. This can 
improve the performance of the load for wave audio and digital video 
devices. This flag can only be used in conjunction with the 
MCI_OPEN_ELEMENT flag. Specifying this flag disables 

MCI.RECORD and MCI.SAVE. 

MCI_OPEN_ALIAS 

This flag specifies that the pszAlias field of the open structure contains an 
alias for this device instance. This alias can then be used on subsequent 
commands using the string interface. 
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MCI_OPEN_TYPE_ID 

The pszDeviceType field of the open structure is to be interpreted as fol¬ 
lows. The low-order word is a standard device type and the high-order 
word is the ordinal index for that device type. If this flag is specified and 
the high-order word is 0, then the default device of that type is opened. If 
this flag is not specified and the pszDeviceType field is not NULL, 
MMPM/2 will attempt to open the device specified by the string pointed to 
by pszDeviceType. 

Digital Video Extensions 

MCI_DGV_OPEN_PARENT 

This flag indicates that the hwndParent field of the open structure con¬ 
tains a valid parent window handle. If this is not specified, then 
HWND_DESKTOP is assumed to be the parent. 

Waveform Audio Extensions 

MCI_OPEN_PLAYLXST 

The pszElement field of the open structure contains a pointer to a memory 
playlist structure. 

Video Overlay Extensions 

M C I_0 VL Y_0 PE N_P ARE NT 

This flag indicates that the hwndParent field of the open structure con¬ 
tains a valid parent window handle. If this is not specified, then 
HWND_DESKTOP is assumed to be the parent. 

pParam2 (PMCI_OPEN_PARMS)—input 

A pointer to the MCI_OPEN_PARMS data structure. Some devices might 
replace this structure with an extended structure. The following devices do 
require an extended open structure. 

• Amp/Mix —This field is a pointer to a MCI_AMP_OPEN_PARMS 
data structure. 

• Digital Video —This field is a pointer to a 

MCI_DGV_OPEN_PARMS data structure. 

• Video Overlay —This field is a pointer to a MCI_OVLYAMP_ 
OPEN_PARMS data structure. 
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Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_I]WALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR_DRIVER 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_DEVICE_LOCKED 

MCIERR_FLAGS_NOT_COMPATTBIJE 

MCIERR_FIL^_NOT_FOlJND 

MCIERR_INI_FILE 


MCIERR_0\^Y_MAX_OPEN_IJnvnT 

MCIERR_INVAIJD_MEDIA_TYPE 

MCIERR.HARDWARE 

MCIERR_FII^E_A1 T 1RIBUTE 

MCIERR_NO_DEVICEDRIVER 

MCIERR_UNSUPP_SAMPLESPERSEC 

MCIERR_UNSUPP_BITSPERSAMPLE 

MCIERR_UNSUPP_CHANNELS 

MCIERR_UNSUPP_FORMAT_MODE 

MCIERR_UNSUPP_FORMAT_TAG 

MMIOERR_ACCESS_DENIED 


Remarks 


Case is ignored in the device name, but there must not be any leading or trail¬ 
ing blanks. Note that the device type is the pszDeviceType element of the 
MCI_OPEN_PARMS structure, but it does not have a corresponding flag 
because it is required and does not have a command-string parameter. Also, if 
automatic type selection is desired (through the extensions or EA section or 
INI), the file name (including file extension) must be passed in the 
pszElementName parameter, the pszDeviceType is left NULL, and the 
MCI_OPEN_ELEMENT flag is set. 

If a parent window handle is specified, but the window handle is invalid, the 
overlay device opens successfully, but uses HWND_DESKTOP as its parent. 
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MCI_PASTE 


MCLPASTE 

This message issues a delete on the selected range and inserts the data from 
the clipboard or application buffer into the file start at the from position. The 
media position after the paste operation is at the end of the pasted data. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI.FROM 

Marks the beginning position of the paste operation. The position of the 
media will either be the position specified in the MCI_FROM or the pre¬ 
vious position if MCI_FROM is not specified. 

MCI_TO 

Marks the ending position of the paste. 

MCI_CONVERT_FORMAT 

Converts data in the clipboard to a destination format. 

MCI_TO_BUFFER 

Places data from the clipboard into the application’s buffer. If this flag is 
not specified, the data is placed in a file. 

MCI_FROM_BUFFER 

Places data from the application’s buffer into the file. If this flag is not 
specified, the clipboard is used as the source. 

pParam2 (PMCI_EDIT_PARMS)—input 

A pointer to the MCI_EDIT_PARMS data structure. 
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Returns 


MCIERR.SUCCESS MCIERR_INSTANCE_INACTIVE 

MCIERR_INVALID_BUFFER MCIERR_INVALID_CALLBACK_HANDLE 
MCIERR_CANNOT_WRITE MCIERR_OUT_OF_MEMORY 

MCIERR.OUTOFRANGE MCIERR_CLIPBOARD_EMPTY 

MCIERR_INVALID_MEDIA MCIERR_CANNOT_CONVERT 

MCIERR_INVALID_DEVICE_ID MMIOERR_CLIPBRD_EMPTY 
MCIERR_MISSING_PARAMETER MMIOERR_CLIPBRD_ERROR 
MCIERR_INVALID_FLAG MMIOERR_INCOMPATIBLE_DATA 

MCIERR_UNSUPPORTED_FLAG 


Remarks 


The units of the MCI_FROM and MCI_TO parameters must be supplied in 
the selected time format. If neither MCI_FROM or MCI_TO is specified, 
MCI_PASTE inserts the clipboard contents at the current position. 

The MCI_CONVERT converts what was in the clipboard to the destination 
file format. The following conversions can be done: 


Settings Conversion 

Channels: Mono to stereo, stereo to mono. 

Sampling rate: 11025, 22050, or 44100 to 11025, 22050, or 44100 
Data Type: 16-bit to 8-bit, 8-bit to 16-bit. 

Note: No smoothing is performed on the paste. If paste interrupts an in¬ 
progress operation, the command is aborted and an aborted notification mes¬ 
sage is sent. 

The implementation of the paste operation for AVI movie files does not support 
data transformations. The AVI movie file being pasted into must have the 
same video and audio characteristics as the file from which the clipboard data 
was obtained. (The video data must have the same nominal frame rate, frame 
size, and use the same decompressor: the audio data must be the same type 
and must match in numbers of channels, samples per second, and bits per sam¬ 
ple.) MMIOERR_INCOMPATIBLE_DATA is returned if the clipboard data 
does not match the data in the target file. 

Edited Audio/Video Interleaved (AVI) movie files cannot always be saved with 
their original name after the paste operation. If the clipboard contains a refer¬ 
ence to data that would be erased during saving or if another instance of the 
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digital video device has a pending paste operation which depends on this data, 
the file cannot be saved unless a new file name has been provided. If a new file 
name is not provided, MMIOERR_NEED_NEW_FILENAME is returned by 
the AVI I/O procedure and a temporary new file is created to save the edited 
movie. 

The MCI_CONVERT, MCI_TO_BUFFER, and MCI_FROM_BUFFER flags 
are not supported by the digital video device. 

Waveaudio Specific 

If MCI_FROM_BUFFER or MCI_TO_BUFFER are used, the pHeader field 
of MCI_EDIT_PARMS must contain a pointer to an MMAUDIOHEADER 
structure. The ulBufLen field of MCI_EDIT_PARMS must be filled in. 
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MCIJPAUSE 


MCLPAUSE 

This message is sent to suspend playback or recording. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERRJ3UCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR.INSTANCEJNACTIVE 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INVALID_CALLBACK_HANDLE 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 


Remarks 


The MCI_RESUME message is used to return the device to the previous play¬ 
back or recording operation from the paused state to the parameters of the pre¬ 
vious operation that remain in effect. 

If the device is paused and MCI_PLAY or MCI_RECORD is issued, the previ¬ 
ous action is superseded and from and to parameters are used from the newly 
issued message. 
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MCLPLAY 


MCLPLAY 

This message is sent to begin playback. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCIJFROM 

This flag is used to indicate that the ulFrom field of the play data struc¬ 
ture is to be used. If this flag is not set the current position is assumed as 
the starting position for the play operation. 

MCI_TO 

This flag is used to indicate that the ulTo field of the play data structure 
is to be used. If this flag is not set, the end of the media is assumed as the 
ending position for the play operation. 

Videodisc Extensions 

MCI_VD_PLAY_REVERSE 

This flag specifies to play in reverse 

MCI_VD_PLAY_FAST 

This flag specifies to play at the fast rate. 

MCI_VD_PLAY_SCAN 

This flag specifies to scan. Scan usually means to play as fast as possible 
with audio disabled. 

MCI_VD_PLAY_SPEED 

This flag adds a speed parameter. The units are specified by the currently 
set speed format. The speed value is in the ulSpeed field. 

MCI_VD_PLAY_SLOW 

This flag specifies to play at the slow rate. 
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Digital Video Extensions 

MCI_DGV_PLAY_REVERSE 

This flag specifies to play in reverse. 

MCI_DGV_PLAY_FAST 

This flag specifies to play at the fast rate. 

MCI_DGV_PLAY_SCAN 

This flag specifies to scan. Scan usually means to play as fast as possible 
with audio disabled. 

MCI_DGVJPLAY_SPEED 

This flag adds a speed parameter. The units are specified by the currently 
set speed format. The speed value is in the ulSpeed field. 

MCI_DGV_PLAY_SLOW 

This flag specifies to play at the slow rate. 

mci_dgv_play_repeat 

This flag specifies that the play operation be repeated until the command 
is superseded or aborted. 

pParam2 (PMCI_PLAY_PARMS)—input 

A pointer to the MCI_PLAY_PARMS data structure. Some devices might 
replace this structure with an extended structure. The following devices do 
require an extended open structure. 

• Digital Video —This field is a pointer to a 

MCI_DGV_PLAY_PARMS data structure. 

• Videodisc —This field is a pointer to a MCI_VD_PLAY_PARMS 
data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_MEDIA_CHANGED 

MCIERR_DEVICE_NOT_READY 

MCIERR_INVALID_DEV[CE_rD 

MCIERR_INSTANCE_INACTIVE 

MCIERR_MISSING_FLAG 

MCJERR_UNSUPPORTED_FLAG 


MCIERR_INVAIJD_CAIJJBACK_HANDLE 

MClERR_UNSUPPORTED_FUNCIION 

MCIERR_INVALro_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR.OUTOFRANGE 

MCIERR_MISSING_PARAMETER 

MCIERR_CHANNEL_OFF 
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Remarks 


The parameters and flags for this message vary according to the selected 
device. The units of the MCI_FROM and MCI_TO parameters must be sup¬ 
plied in the currently selected time format. See the MCI_SET message and the 
MCI_SET_TIME__FORMAT flag for more information. 

The following example illustrates how the MCIJFROM and MCI_TO parame¬ 
ters are interpreted. If a multimedia element is composed of samples, in a file 
with 100 samples, the samples are numbered from 0 to 99. If MCIJFROM is 
specified as 10 and MCI_TO is specified as 80, MCI_PLAY will play samples 
10 through 79. Following the play operation, the current position of the media 
would be 80. 

If the length of a file cannot be determined, MCIERR_SUCCESS might be 
returned even if the MCI_TO parameter is out of range. 
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MCI_PUT 


MCLPUT 

This message sets the source and destination rectangles for the transformation 
of the video image and the position of the default video window. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 


Digital Video Extensions 

mci_dgv_put_rect 

This flag specifies that the rc field contains a valid display rectangle 
array. This is a required parameter. 

MCI_DGVJPUT_SOURCE 

This flag indicates that the rc field contains a display rectangle array 
specifying the offset and size of a clipping rectangle for the digital video 
source image. The source rectangle array specifies a capture rectangle rel¬ 
ative to the digital video origin. MCI_DGV_PUT_SOURCE can only be 
used with MCI_DGV_RECORD. The size of the origin (or source) can be 
found using MCI_DGV_STATUS^VIDEO_X_EXTENT and 
MC I_D GV_STATU S_VIDE 0_Y_EXTENT. 

MC I_D GV_PUT_DE STINATION 

This flag indicates that the rc field contains a display rectangle array 
specifying the offset and visible extent of the digital video within the 
client window. The destination rectangle array specifies a clipping rectan¬ 
gle for frames relative to the lower left corner of the window. When 
MCI_DGV_PUT_DESTINATION is used with MCI_DGV_MONITOR, 
the size and position of the monitor video relative to the monitor window 
is determined. If MCI_DGV_PUT_DESTINATION is used without 
either MCI_DGV_MONITOR or MCI_DGV_RECORD, the size and 
position of the playback video relative to the playback window is 
determined. 
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MCI_DGV_PUT_WINDOW_MOVE 

This flag indicates that the rc field contains a display rectangle specifying 
the window position. All four values (XI Y1 X2 y2) must be specified, but 
X2 and Y2 are ignored unless the MCI„DGV_PUT_WINDOW_SIZE 
parameter is also specified. 

MCI_DGV_PUT_WINDOW_SIZE 

This flag indicates that the rc field contains a display rectangle that 
specifies the size of the window. All four values (XI Y1 X2 Y2) must be 
specified. 

MCI_DGV_RECORD 

This flag specifies the source and destination rectangles are for video 
capture. 

MCI_DGV_MONITOR 

This flag specifies the size and position for monitor window. 

Video Overlay Extensions 

MCI_OVLY_PUT_RECT 

Specifies that the rc field of the data structure identified by pParam2 con¬ 
tains a valid display rectangle. 

MCI_OVLY„PUT_SOURCE 

Indicates that the rc field of the data structure identified by pParam2 
contains a display rectangle for the analog video source. The source rec¬ 
tangle specifies the portion of the incoming video signal which will be dis¬ 
played. If MCI_OVLY_PUT_SOURCE is specified without the 
MCI_OVLY_PUT_RECT parameter, the default source is set. 

MCI_OVLY_PUT_DESTINATION 

Indicates that the rc field of the data structure identified by pParam2 
contains a display rectangle for the video overlay within the client win¬ 
dow. The destination rectangle specifies a clipping rectangle for frames 
relative to the lower-left corner of the window. If 
MCI_OVLY_PUT_DESTINATION is specified without the 
MCX_OVLY_PUT_RECT parameter, the default destination is set. 
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MCI_OVLY_PUT_WINDOW_MOVE 

Indicates that the rc field of the data structure identified by pParam2 
contains a display rectangle, where the X! Y! coordinates are relative to 
the parent window. The X2 and Y2 coordinates are ignored unless the 
MCI_OVLY_PUT_WINDOW_SIZE parameter is also specified. 

MCI_OVLY_PUT_WINDOW_SIZE 

Indicates that the rc field of the data structure identified by pParam2 
contains a display rectangle. The new default window size is calculated to 
((X2-X1) +1) and ((Y2-Y1) +1). 

pParam2 (PVOID)—input 

For digital video devices this is a pointer to a MCIJDGV_RECT_PARMS 
data structure and for video overlay device it is a pointer to 

MCI_OVLYJRECT_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERRJDRIVER 


MCIERR_INVALID_FLAG 

MCIERR_MXSSING_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERRJNSTANCEJNACTIVE 


Remarks 


Not all devices support distorting the source rectangle image to fit the display 
rectangle. The MCI.GETDEVCAPS message (MCI_DGV_GETDEVCAPS_ 
CAN_DISTORT) can be used to determine whether the device supports 
distorting. 

If either the width or the height of the rectangle specified with 
MCI_DGV_PUT_DESTINATION and MCI_DGV_RECORD is not a multi¬ 
ple of eight, then that value is rounded to the nearest multiple of eight. If the 
device cannot distort and the rectangle specified with 
MCI_DGV_PUT_SOURCE and MCI_DGV_RECORD is not an integral mul¬ 
tiple of the rectangle specified with MCI_DGV_PUT_DESTINATION and 
MCI_DGV_RECORD, the source and destination rectangles are adjusted to 
find the nearest value that will make the source be an integral multiple of the 
destination and the destination be a multiple of eight. 
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When the device is monitoring while recording or monitoring while cued for 
input, the video seen in the monitor window will be the content in the record 
source rectangle set with MCI_DGV_PUT_SOURCE and 
MCI_DGV_RECORD. When the device is monitoring while not recording or 
cued for input, the video seen in the monitor window will be the maximum 
source (full video extent of the capture card reported by MCI_DGV_STA- 
TUS__X_EXTENT and MCI_DGV_STATUS_Y_EXTENT), and an animated, 
dashed-line rectangle will be drawn on the monitor window to indicate the rel¬ 
ative position of the record source rectangle. 

If both window and size flags are specified, then all four window coordinates 
must be provided. 
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MCI_RECORD 


MCLRECORD 

This message causes the device to start recording. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_FROM 

Indicates a starting position is included in the ulfrom field of the data 
structure pointed to by pParam2. The units assigned to the position val¬ 
ues are specified with the MCI_SET_TIME_FORMAT flag of the 
MCI_SET command. If MCI_FROM is not specified, the starting posi¬ 
tion defaults to the current location. The ulFrom field refers to a position 
in the destination media. 

MCI_TO 

Indicates an ending position is included in the ulTo field of the data struc¬ 
ture pointed to by pParam2. The units assigned to the position values are 
specified with the MCI_SET__TIME_FORMAT flag of the MCI.SET 
command. If MCI_TO is not specified, the record will continue until a 
pause or stop message is received. The ulTo field refers to a position in 
the destination media. 

MCI_RECORD_INSERT 

Indicates that newly recorded information is to be inserted into existing 
data at the current location. Some devices, such as non-file-oriented 
devices, do not support this. 

MCI_RECORD_OVERWRITE 

Indicates that recorded data is to overwrite existing data at the current 
location. Note that MCI_RECORD_INSERT and MCI_RECORD_ 
OVERWRITE are mutually exclusive. 
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Digital Video Extensions 


MCI_DGV_RECORD_RECT 

Indicates that the rc field of the data structure identified by pParam2 con¬ 
tains a display rectangle array specifying the offset and size of a clipping rec¬ 
tangle for the digital video source image to be recorded. The source rectangle 
array specifies a display rectangle relative to the digital video origin. 

pParam2 (PMCI_RECORD_PARMS)—input 

A pointer to the MCX_RECORD_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_INSTANCE_INAC r nVE 

MCIERR_MISSEVG_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVALID_CAIJ,BACK_HANDLE 

MCIERR_UNSUPPORTED_FUNCTION 


MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_FILE_NOT_FOUND 

MCIERR_MISSING_PARAMETER 

MCIERR.OUTOFRANGE 

MCIERR_OlJT_OF_MEMORY 

MCIERR_TARGET_DEVICE_FUIJL 


Remarks 

The units of the MCI_FROM and MCI_TO parameters must be supplied in 
the currently selected time format. See the MCI_SET message and the 
MCX_SET_TXME_FORMAT flag for more information. 

Only devices that return TRUE to the MCI_GETDEVCAPS_CAN_RECORD 
flag of the MCI_GETDEVCAPS command support this message. 

A STOP is performed implicitly if the device is not stopped when 
MCX_RECORD is issued. If a STOP is issued during recording, MCI_NOTI- 
FY_ABORTED will be returned. If an MCI_TO position is specified on a 
record operation and the record operation completes, MCI_NOTIFY_SUC- 
CESSFUL is returned. 
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MCI_REDO 


MCLREDO 

This message redoes the cut, paste or delete operation most recently undone by 
the MCI_UNDO operation. The media position is at the beginning of the file 
after a redo. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR.SUCCESS MCIERR_INSTANCE_INACTIVE 

MCIERR_INVALIDJDEVICE_ID MCIERR_INVALID_CALLBACK_HANDLE 
MCIERR_INVALID_FLAG MCIERR_CANNOT_REDO 

Remarks 

Redo operates on one editing action (for example, cut, delete, paste) at a time. 
If there are no more possible actions to be redone (that is, the file is in the state 
where the last change was made), then MCIERR_CANNOT__REDO is 
returned. 

Note: Redo is unlimited. However, after a save, any previous editing actions 
are cleared and cannot be redone. 

After a redo operation, the position in the media is at the beginning. Not all 
devices support this message. To determine if a device supports MCI_REDO, 
issue an MCI_GETDEVCAPS message. 

If redo interrupts an in-progress operation, the command is aborted, and an 
aborted notifications message will be sent. 



460 Developing Multimedia Applications Under 05/2 


MCI_RELEASEDEVICE 


MCI_RELEASEDEVICE 

This message is sent to release the exclusive or exclusive instance use of the 
physical resources by a group or device instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_RETURN_RESOURCE 

This flag release a device instance from the active state and makes the 
next available inactive device instance active. The device instance will not 
be made active again unless MCI_ACQUIREDEVTCE is issued for this 
device instance, or no other application is using the device. If the instance 
is already inactive, the message is ignored. 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR_SUCCESS MCIERR_INVALID_FLAG 

MCIERR_INVALID_DEVICE_ID MCIERR_FLAGS_NOT_COMPATIBLE 


Remarks 

Releasing a device does not always cause the device to be passed to another 
application. Ownership of a device is changed only when the 
MCI_ACQUIREDEVTCE message is used, or if another application closes or 
opens a device. 
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MCI_RESTORE 


MCLRESTORE 


This message causes a video device to transfer an image from the element 
buffer to the display surface. To ensure that the image is displayed, the device 
automatically performs a freeze operation where necessary. 


Parameters 


ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_RESTORE_SRC_RECT 

The SrcRect field of the MCI_RESTORE_PARMS data structure con¬ 
tains the rectangle specifying the area to be restored from the capture 
device element. If this is not specified, the entire image is restored. 

mci_restore_dest_rect 

The DestRect field of the MCI_RESTORE_PARMS data structure con¬ 
tains the rectangle specifying the destination area of the window to be 
restored. If this is not specified, the destination size is assumed to be the 
same as the image size in device coordinates placed at the lower left cor¬ 
ner of the window. 

pParam2 (PMCIJRESTORE JPARMS)— input 

A pointer to the MCIJRESTORE_PARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INSTANCE_INACTIVE 

MCIERR_OVLY_EMPTY_BUFFER 


MCIERR_MISSING_PARAMETER 

MCIERR_DRIVER 

MCIERR_INVALID_FLAG 

MCIERR_OVLY_INVALID_RECT 

MCIERR_OVLY_NOT_AVAILABLE 
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Remarks 


The image is restored from the device element in an overlay video device. It is 
also restored from the still image device element of a digital video device. In 
the case of overlay video and digital video devices implemented on dual-plane 
video hardware, the image is restored to the video or image player 

Devices capable of scaling the image will attempt to do so in order to transform 
the output to the destination rectangle. If a destination rectangle is not speci¬ 
fied, or of the device is not capable of scaling the image, the output is clipped to 
the destination rectangle as required. 
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MCLRESUME 


MCLRESUME 

This message is sent to resume playing or recording from a paused state. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCEERR_INSTANCE_INACTIVE 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INVALID_CALLBACK_HANDLE 

MCEERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 


Remarks 


The previously specified to parameter remains in effect. 
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MCI_REWIND 


MCLREWIND 

This message seeks the media to the starting position. The position is defined 
as the first playable area, beyond any header or table-of-contents data. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCIJTENERICJPARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_DEVICE_LOCKED 


MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_INVALro_CAIJLBACK_HANDLE 


Remarks 


This message is the equivalent of the MCI_SEEK message with the 
MCI_TO_START flag specified. 
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MCI_SAVE 


MCI_SAVE 

This message saves the current file. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SAVE_FILE 

The pszFileName field of the MCI_SAVEJPARMS data structure con¬ 
tains the destination file name. If a file name is not specified the original 
file opened or the most recently loaded file name is assumed. 

Digital Video Extensions 

MCI_DGV_SAVE_VIDEO_FILE 

Saves the motion video device element. sAVE 

MCI_DGV__SAVEJMAGE_FILE 

Not supported. 

pParam2 (PMCI_SAVE_PARMS)—input 

A pointer to the MCI_SAVEJPARMS data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERRJCWALrojDEVICEJD 

MCEERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_FILE_NOT_SAVED 

MCIERR_FILE_ATTRIBUTE 


MCIERR_INVALID_CALLBACK_HANDLE 

MCIERR.DRIVER 

MCIERR_TARGET_DEVICE_FULL 

MCIERR_OVLY_EMPTY_BUFFER 

MCIERR_FILE_NOT_FOUND 

MMIOERR_NEED_NEW_FILE_NAME 

MMIOERR_CLIPBRD_ACTIVE 
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Remarks 


The MCI_DGV_SAVE_VTDEO_FILE flag is not required; saving a video file 
is assumed by default. An edited AVI movie file cannot always be saved with 
its original name. If the clipboard contains a reference to data that would be 
erased during saving or if another instance of the digital video device has a 
pending paste operation that depends on this data, the file cannot be saved 
unless a new file name is provided. If a new file name is not provided, the error 
code MMIOERR_NEED_NEW_FILENAME is returned by the AVI I/O proce¬ 
dure, and a temporary file is created to save the edited movie. The AVI I/O pro¬ 
cedure alerts the user by displaying a message with the name of the temporary 
file that was created. The application must reopen the temporary file to use the 
edited version of the movie. 

During setup for MMXOM_SAVE processing, the AVI I/O procedure checks to 
see if the clipboard contains data from a file and if the file needs to be rewrit¬ 
ten. If these conditions are true, the save operation is aborted and an error 
code of MMIOERR_CLIPBRD_ACTIVE is returned. 

If the MCI_SAVE_FILE flag is specified, the current device element is saved 
with the file name specified in pszFileName. The file specified in the 
pszFileName becomes the currently loaded element. If the MCI_SAVE_FILE 
flag is not specified or if pszFileName is null, MCI_SAVE saves to the current¬ 
ly loaded element name of the device instance. If the current element has not 
been named, MCIERR_FILE_NOT_FOUND is returned. 

This command is supported by devices which return TRUE to the MCI_GET- 
DEVCAPS_CAN_SAVE query of the MCI_GETDEVCAPS message. If this 
message is issued without the MCX_SAVE_FILE flag and no file element is 
currently loaded, the MCIERR_FXLE_NOT_FOUND message is returned. 
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MCI_SEEK 


MCI_SEEK 

This message is sent to change the current media position of the device. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI__TO 

This flag adds a ulTo parameter in the data structure pointed to by 
pParam2. If the TO position is beyond the end of the media or segment, 
an MCIERR_OUTOFRANGE error is returned. 

MCI_TO_START 

This flag causes the device to seek to the first playable position on the 
media. This is not necessarily position 0. 

MCI_TO_END 

This flag causes the device to seek to the end of the media. 

Digital Video Extensions 

MCI_DGV_TO_NEAREST_IFRAME 

Seeks to the nearest I-frame preceding the point specified by MCI_TO. 
Videodisc Extensions 

MCI_VD_SEEK_REVERSE 

This flag initiates a seek backward. 
pParam2 (PMCI_SEEK_PARMS)—input 

A pointer to the MCI_SEEK_PARMS data structure. 
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Returns 


MCIERR_SUCCESS 

MCDERR_INVALID_DEVICE_ID 

MCIERR_1NSTANCE_INACTIVE 

MdERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_DSfVALID_CALLBACK_HANDLE 


MCIERRJHARDWARE 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_FILE_NOT_FOUND 

MC1ERR_MISSING_PARAMETER 


Remarks 

The parameters and flags for this message vary according to the selected 
device. The values of the MCI_TO parameters must be specified in the cur¬ 
rently selected time format. See the MCI__SET message and the 
MCI_SET_TIME_FORMAT flag for more information. 

The following example illustrates how the MCI_TO parameter is interpreted. 
If a multimedia element is composed of samples in a file with 100 samples, the 
samples are numbered from 0 to 99. If MCI_TO is specified as 0, the media is 
positioned at its start. If an MCI_PLAY message is issued, the first sample 
would be the first to play. If MCI_TO is specified as 99, the media is positioned 
before the last sample. Issuing an MCI_PLAY message would play the last 
sample. Specifying MCI_TO_END would position the media at the end of the 
file and the current position would be 100. At this point, if an MCI_PLAY 
message is issued, the command would return successfully without performing 
any operation. 
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MCI_SET 


MCI_SET 

This message is used set device parameters or information. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SET_AUDIO 

Sets audio attributes of the device instance. A device with audio capabili¬ 
ties might support both left and right channels. The channel is specified 
in the ulAudio field of the data structure specified by pParam2. The 
action to be taken is specified with the flags MCI_SET_ON (which 
enables audio output at the current volume level), MCI_SET_OFF 
(which mutes audio output), or MCI_SET_VOLUME. Specifying 
MCI_SET_VOLUME does not enable audio output if MCI_SET_OFF 
has been previously specified. 

The following constants are defined for specifying the audio channel in the 
ulAudio field: 

MCI_SET_AUDIO_ALL 

Applies to both channels. 

MCI_SET_AUDIO_LEFT 

Applies to the left channel only. 

MCI_SET_AUDIO_RIGHT 

Applies to the right channel only. 

MCI_SET_DOOR_OPEN 

Instructs the device to open the media cover (if any). 

MCI_SET_DOOR_CLOSED 

Instructs the device to close the media cover (if any). 

MCI_SET_DOOR_LOCK 

Locks the media cover on the device (if any). This disables manual ejec¬ 
tion of the media from the device. 
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MCI_SET_DOOR_UNLOCK 

Unlocks the media cover on the device(if any). This enables manual ejec¬ 
tion of the media from the device. 

MCI_SET_VOLUME 

Sets the level of audio as a percentage of the maximum audio level as 
indicated in the ulLevel field. The volume level that can be set on the 
device might be of coarser granularity than that specified. In this case the 
actual level can be obtained by issuing a MCI_STATUS message. If a 
number greater than 100 is given, then 100 will be used as the volume 
setting, and no error will be returned. 

MCI_SET_VIDEO 

Sets the video signal on or off. This flag must be used with either 

MCI_SET_ON or MCI_SET_OFF. 

MCI_SET_ON 

Sets the video or specified audio channel on. 

MCI_SET_OFF 

Sets the video or specified audio channel off. 

MCI_SET_SPEED_FORMAT 

Specifies the speed format to be used on subsequent commands contained 
in the ulSpeedFormat field. The following values can be used: 

MCI_FORMAT_PERCENTAGE 

Specifies the subsequent speed values as a percentage of the normal 
speed. 

MCI_FORMAT_FPS 

Specifies the subsequent speed values in frames per second. This is 
the default setting. 

MCI_SET_TIME_FORMAT 

Uses a time format on subsequent commands. A time-format parameter 
must be indicated in the ulTimeFormat field of the set data structure. 
The following time format are generic; devices can also provide device¬ 
specific time units: 
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MCI_FORMAT_MILLISECONDS 

Indicates that all subsequent commands that specify time will do so 
in milliseconds for both input and output. 

MCI_FORMAT_MMTIME 

Indicates that all subsequent commands that specify time will do so 
in MMTIME units for both input and output. This does not apply to 
command parameters that explicitly specify time units such as mil¬ 
liseconds. 

MCI.OVER 

Sets the vectored delay time to change the volume or other attributes 
in milliseconds. 

MCI_SET_ITEM 

Indicates that the item to be set is specified in the ulltem field of the 
set data structure. Any value associated with the item is contained in 
the ulValue field. Each item defines the use and meaning of the value 
in the ulValue field. 

Amplifier Mixer Extensions 

MCI_AMP_SET_TREBLE 

Controls treble as a percentage of the maximum achievable effect. 

MCI_AMP_SET_BASS 

Controls bass as a percentage of the maximum achievable effect. 

MCI_AMP_SET_BALANCE 

Sets the final output balance. Zero is defined as full left balance while one 
hundred is defined as full right balance. 

MCI_AMP_SET_PITCH 

Controls pitch as a percentage of the maximum achievable effect. 

MCI_AMP_SET_GAIN 

Controls gain as a percentage of the maximum achievable effect. 

MCI_AMP_SET_MONITOR 

Used with the MCI_SET_ON and MCI_SET_OFF flags. It instructs the 
ampmix device to monitor the currently selected connector. This function 
is typically used to listen to or monitor a source while it is being recorded 
by another device. 
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CD Audio Extensions 


MCI_FORMAT_MSF 

Indicates that all subsequent commands that specify time will do so in 
mm:ss:ff where mm is minutes, ss is seconds and ff is frames. 

MCI_FORMAT_TMSF 

Indicates that all subsequent commands that specify time will do so in 
tt:mm:ss:ff where tt is tracks, mm is minutes, ss is seconds and ff is 
frames. 

Digital Video Extensions 

MCI_DGV_SET_VIDEO_COMPRESSION 

Specifies the FOURCC compression format used for recording digital 
motion video. The default compression type is specified through the setup 
page for the digital video device. The initial setting is 
MCI_VID_COMP_ULTI until changed via the setup page. The values 
that can be specified are: 

MC I_VID_C OMP_ULTI 

Ultimotion. 

MC I_VID_C OMP_DIB 

Raw video. 

MCI_VID_COMP_RT21 

Indeo. 

MCI_DGV_SET_RECORD_AUDIO 

Sets audio soundtrack recording on or off. The default is MCI_ON. This 
flag is used with MCI_ON or MCI_OFF. 

MCI_DGV_SET__REF_INTERVAL 

Sets the frequency at which reference frames (or I-frames) are to be com¬ 
pressed in the output data stream. A value of 0 results in no I-frames, a value 
of 1 causes every frame to be an I-frame, a value of 2 causes every other frame 
to be an I-frame, and so on. While there is no upper bound on the reference 
frame interval, a reference frame interval of 2 seconds or less produces the 
best results. The default reference frame interval is every 15th frame (once a 
second at the default frame rate of 15 frames per second). 
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MCI_DGV_SET_BRIGHTNESS 

Sets the brightness level in the range 0-100. 

MCI_DGV_SET_CONTRAST 

Sets the contrast level in the range 0-100. 

MC I_D G V_SET_HUE 

Sets the hue level in the range 0-100, where 0 indicates maximum green 
tint, 100 indicates maximum red tint, and 50 indicates a neutral tint. 

MCI_DGV_SET_SATURATION 

Sets the saturation level in the range 0-100. 

MCI_DGV_SET_VIDEO_QUALITY 

Specifies the compression quality level setting to be sent to the CODEC. 
This value is in the range 0-10,000. Not all CODECs support setting a 
quality level. The default setting for video quality is 5,000. 

MCI_DGV_SET_MONITOR 

Sets monitoring of the incoming video signal on or off. Must be used in 
conjunction with MCI_SET_ON or MCI_SET_OFF. The default setting 

is MCI.SETOFF. 

MCI_DGV_SET_CHANNELS 

Sets the number of channels in the audio soundtrack recording (l=mono, 
2=stereo). The default is 1. 

MCI_DGV_SET_SAMPLESPERSEC 

Sets the number of waveform audio samples per second in the audio 
soundtrack recording. This value is usually 11025, 22050 or 44100. The 
default is 11025. 

MCI_DGV_SET_BITSPERSAMPLE 

Sets the waveform audio sample size for the audio soundtrack recording. 
This value is usually 8- or 16-bits. The default is 8. 

MCI_DGV_SET_TRANSPARENT_COLOR 

Sets the transparent color used as the chroma-key value on video overlay 
hardware. The color is set as a numeric value in the range 0...n-l. Where 
n represents the number of available colors. 
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MCI_DGV_SET_VIDEO_RECORD_RATE 

Sets the frame rate for recording as an integral number of frames per sec¬ 
ond in the range 0-30. This sets the target capture rate, but there is no 
guarantee this rate will be attained. Drop frame records will be inserted 
into the output data stream to indicate frames dropped during the record 
process. The default record frame rate is 15 frames per second. 

MCI_DGV_SET_VIDEO_RECORD_FRAME_DURATION 

Sets the frame rate for recording as the time duration of each frame in 
microseconds. This is useful for setting non-integer frame rates, for exam¬ 
ple, 12.5 fps of a PAL videodisc: 1000000/12.5=8000 microseconds. The 
default frame duration is 66,667 microseconds (equivalent to 15 fps). 

The following additional time formats are supported by digital video devices 
and can be specified as values for the ulTimeFormat field: 

MCI_FORMAT_MILLISECONDS 

Changes the time format to milliseconds. 

MCI_FORMAT_MMTIME 

Changes the time format to MMTIME. 

MCI_FORMAT_FRAMES 

Changes the time format to frames. 

MCI_FORMAT_HMS 

Changes the time format to hours, minutes, and seconds. 

MCI_FORMAT_HMSF 

Changes the time format to hours, minutes, seconds, and frames. 

Sequencer Extensions 

MCI_SEQ_SET_MASTER 

Sets the sequencer as a source of synchronization data and indicates that 
the type of synchronization is specified in the ulMaster field. The follow¬ 
ing constants are defined for the synchronization type: 

MCI_SEQ_MIDI 

The sequencer will send MIDI format synchronization data. 

MCI_SEQ_SMPTE 

The sequencer will send SMPTE format synchronization data. 
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MCI_SEQ_NONE 

The sequencer will not send synchronization data. 

MCI_SEQ_SET_OFFSET 

Changes the SMPTE offset of a sequencer to that specified by the ulOffset 
field. This only affects sequences with a SMPTE division type. 

MCI_SEQ_SET_PORT 

Sets the output MIDI port of a sequencer to that specified by the MIDI 
device ID in the ulPort field. The device will close the previous port and 
attempt to open and use the new port. If it fails, it will return an error 
and reopen the previously used port. The following constants are defined 
for the ports: 

MC I_SET_N ONE 

Closes the previously used port. The sequencer will behave exactly the 
same as if a port were open, except no MIDI message will be sent. 

MCI_MIDI_MAPPER 

Sets the port opened to the MIDI mapper. 

MCI_SEQ_SET_SLAVE 

Sets the sequencer to receive synchronization data and indicates the type 
of synchronization is specified in the ulSlave field. The following con¬ 
stants are defined for the synchronization type: 

MCI_SEQ_FILE 

Sets the sequencer to receive synchronization data contained in the MIDI 
file. 

MCI_SEQ_MIDI 

Sets the sequencer to receive MIDI format synchronization data. 

MC I_SE Q_SMPTE 

Sets the sequencer to receive SMPTE format synchronization data. 

MCI_SEQ_NONE 

Sets the sequencer to ignore synchronization data in a MIDI stream. 
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MCI_SEQ_SET_TEMPO 

Changes the tempo of the MIDI sequence to that specified by the ulTempo 
field. For sequences with division type PPQN, temp is specified in beats 
per minute; for sequences with division type SMPTE, tempo is specified in 
frames per second. Currently this function is not supported by the IBM 
sequencer. 

The following additional time-format flags apply to MIDI device devices: 
M[CI_SEQ_SET_SM[PTE_24 
Sets the time format to 24 frame SMPTE. 

MCI__SEQ__SET_SMPTE_25 

Sets the time format to 25 frame SMPTE. 

MCI_SEQ_SET_SMPTE_30 

Sets the time format to 30 frame SMPTE. 

MCI_SEQ_SET_SMPTE_30DROP 

Sets the time format to 30 drop-frame SMPTE. 

MCI_SEQ_SET_SONGPTR 

Sets the time format to song pointer units. 

Videodisc Extensions 

MCI_VD_SET_CHANNEL 

This flag sets the video channel to the channel specified in the ulChannel 
field. 

MCI_VD_SET_VIDEO 

This flag sets video. 

MCI_VD_SET_DISPLAY 
This flag sets the display index. 

MCI_VD_SET_ON 

This flag sets videodisc driver on. 

MCI_VD_SET_OFF 

This flag sets videodisc driver off. 
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The following additional time formats apply to videodisc devices: 
MCI_FORMAT_CHAPTER 
This flag changes the time format to chapters. 

MCI_FORMAT_FRAMES 

This flag changes the time format to frames. 

MCI_FORMAT_HMS 

This flag changes the time format to hours, minutes, and seconds 

MCI_FORMAT_HMSF 

This flag changes the time format to hours, minutes, seconds, and frames. 
Video Overlay Extensions 

The following additional items apply to video overlay devices and can be speci¬ 
fied for the ulltem field: 

MCI_OVLY_SET_IMAGE_FILE_FORMAT 

Sets the specified image file format in which the image capture is to be 
stored (when saved). This format must be specified by a four-character 
code (for example, MMOT, or OS13) and must be one of the currently sup¬ 
ported and installed MMIO image file formats, or the device-specific for¬ 
mat. This does not effect the loading or restoring of images. It overwrites 
any previous file-format value, such as that obtained through a LOAD 
command. 

MCI_OVLY_SET_IMAGE_COMPRESSION 

This flag sets the compression type used for saving still images. The spec¬ 
ified compression type is used if it is supported by the device, the file for¬ 
mat, or both. The compression type is not used if it contradicts settings 
for file format, BITSPERPEL, or PELFORMAT. If the compression type 
value is valid, it supersedes any image quality setting and overwrites any 
format tag or compression value obtained by a LOAD operation. However, 
it does not affect the loading or restoring of images. Compression algo¬ 
rithms are often proprietary and can require hardware assistance for per¬ 
formance. Therefore, when possible, the setting of this item is controlled 
by the device. If the specified compression type is not compatible with file 
format or BITSPERPEL settings, the device selects a compression type 
based on the file format, PELFORMAT, and quality settings. If the com¬ 
pression type is not available, the device returns function not supported 
and uses the current setting. 
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M-Motion specific: The default is MCI_IMG_COMP_NONE. 
MCI_OVLY_SETJMAGEBITSPERPEL 

Sets the number of bits per pixel used for the image file to be saved. 
Generally supported values are those defined for OS/2 2.0 bitmaps. Some 
devices might support other values. 

The value specified for this setting might not be the same as the number 
of colors currently visible on the display. Selecting a BITSPERPEL value 
greater than that currently displayed results in unused colors. Selecting a 
value less than that currently displayed results in a degradation of color 
and a reduced quality image. 

Most file formats do not support all BITSPERPEL values. This item over¬ 
writes any BITSPERPEL value obtained by a LOAD operation. However, 
it does not affect the loading or restoring of images. 

Some devices are not capable of adjusting the number of colors to be 
saved in the image file. When this is the case, the device captures and 
saves the image in whatever number of colors it supports. The actual 
value used can be obtained using the 

MCI_OVLY_STATUS_IMAGE_BITSPERPEL flag. 

If variable BITSPERPEL representation is not available, the device 
returns function not supported and uses the current setting. 

M-Motion specific: The default is 12. 

MCI_OVLY_SET_IMAGE_PELFORMAT 

This flag sets the pixel format used for saving bit maps. This value indi¬ 
cates the desired image file color representation, and it is used in conjunc¬ 
tion with the BITSPERPEL value. Supported pixel format values are: 

MCIJMGJPALETTE 

A palettized video image with 1-, 4-, or 8-bits per pixel. 

MCIJMGJRGB 

An RGB video image with 16- or 24-bits per pixel. 

MCIJMG.YUV 

A YUV video image with 9-, 12-, or 16-bits per pixel. 

Most file formats do not support all pixel formats. This item overwrites 
any pixel format value obtained by a LOAD operation. However, it does 
not affect the loading or restoring of images. Some devices are not capable 
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of adjusting the color representation of the image. When this is the case, 
the device captures and saves the image in whatever color representation 
it supports. If variable color representation is not available, the device 
returns function not supported and uses the current setting. 

M-Motion specific: The default is MCI_XMG_YUV. 

MCI_OVLY_SETJBRIGHTNESS 

This flag sets the brightness level in the range 0-100. 

MCI_OVLY_SET_CONTRAST 

This flag sets the contrast level in the range 0-100. 

MCI_OVLY_SET_HUE 

This flag sets the hue level in the range 0-100. A value of 50 indicates a 
neutral tint. 

MCI_OVLY_SET_SATURATXON 

This flag sets the saturation level in the range 0-100. 

MCI_OVLY_SET_SHARPNESS 

This flag sets the sharpness level in the range 0-100. 

MCI_OVLY_SET_GREYSCALE 

This flag turns the gray scale on or off. Must be used in conjunction with 

MCI_SET_ON or MCI_SET_OFF. 

MCI_OVLY_SET_IMAGE_QUALITY 

This flag sets the specified image quality level. This item indicates the 
perceived quality of the image to be saved and allows the device to select 
the most appropriate compression method when more than one is avail¬ 
able. The value specified for this item can affect the size of the resulting 
file. 

This item overwrites any quality value obtained by a LOAD operation. 
However, it does not affect the loading or restoring of images. If image 
quality is not previously set, the device selects a compression scheme as 
accurately as possible. If variable image quality is not available, the 
device returns function not supported and uses the current setting. 
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Supported values are: 

MCI_IMG_QUALITY_HIGH 

This flag normally describes photo-realistic images with high resolution 
and color content. 

MCI_IMG_QUALITY_MED 

This flag normally describes images such as complete graphs, charts, or 
diagrams, with fewer color transitions and complexity. 

MCI_IMG_QUALITY_LOW 

This flag normally describes images such as cartoons and simple draw¬ 
ings. 

MCI_OVLY_SET_IMAGE_COMPRESSION_METHOD 

This flag sets the method by which image compression or decompression 
is done. Supported values and their meanings are: 

MCI_CODEC_DEFAULT 

This flag selects the default compression method specified in the INI file. 

MCI_CODEC_SW_ONLY 

This flag selects to use software emulation as the compression method. 

MCI_C ODE C_HW 

This flag selects to use the compression method supported by the hard¬ 
ware, if available. Otherwise, software emulation is used. 

mci_ovly_set_minimum_video_refresh_rate 

This flag sets the minimum refresh rate for the device instance. This is 
the minimum frame display refresh rate the application will accept for 
this device instance. This parameter is used on hardware that can multi¬ 
plex the digitization between different windows at reduced rates. The 
default is one, allowing degraded display on hardware that supports this 
capability. 

Waveform Audio Extensions 

MCI_WAVE_SET_FORMATTAG 

Sets the format type used for playing, recording, and saving to 
usFormatTag. The following constants are defined to set format type: 
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MCI_WAVE_FORMAT_PCM 

Changes the format to pulse code modulation (PCM). 

MCI_WAVE_FORMAT_ADPCM 

Changes the format to adaptive differential pulse code modulation 
(ADPCM). 

MCI_WAVE_FORMAT_IBM_CVSD 

Changes the format to IBM Speech Viewer. 

MCI_WAVE_FORMAT_ALAW 
Changes the format to A-law. 

MCI_WAVE_FORMAT_MULAW 
Changes the format to Mu-Law. 

MCI_WAVE_FORMAT_IBM_ALAW 
Changes the format to IBM A-Law. 
MCI_WAVE_FORMAT_IBM_MULAW 
Changes the format to IBM Mu-Law. 
MCI_WAVE_FORMAT_OKI_ADPCM 
Changes the format to OKI ADPCM. 
MCI_WAVE_FORMAT_DVI_ADPCM 
Changes the format to DVI ADPCM. 
MCI_WAVE_FORMAT_IBM_ADPCM 
Changes the format to IBM ADPCM. 

MCI_WAVE_FORMAT_DIGISTD 
Changes the format to IBM Digispeech. 
MCI_WAVE_FORMAT_DIGIFIX 
Changes the format to IBM Digispeech. 

MCI_WAVE_FORMAT_AV C_ADPCM 
Changes the format to AVC ADPCM 
MCI_WAVE_FORMAT_CL_ADPCM 
Changes the format to Creative Labs ADPCM. 
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MCI_WAVE_SET_CHANNELS 

Sets the channel count used for playing, recording, and saving to the 
usChannels field. 

MCI_WAVE_SET_SAMPLESPERSEC 

Sets the samples per second used for playing, recording, and saving to the 
ulSamplesPerSec field. 

MCI_WAVE_SET_AVGBYTESPERSEC 

Sets the bytes per second used for playing, recording, and saving to 
ulAvgBytesPerSec field. 

mci_wave_set_blockalign 

Sets the block alignment used for playing, recording and saving to 
usBlockAlign field. 

MCI_WAVE_SET_BITSPERSAMPLE 

Sets the bits per sample used for playing, recording, and saving to the 
usBitsPerSample field. 

The following additional time format flags apply to wave audio device devices: 

MCI_FORMAT_SAMPLE S 

Changes time format to samples. 

mci_format_bytes 

Changes time format to bytes. 

pParam2 (PMCI_SET_PARMS)—input 

A pointer to the MCI_SET_PARMS data structure. This is the default 
parameter data structure. Devices with additional parameters might replace 
this pointer with a pointer to a device-specific data structure as follows: 

PMCI_AMP_SET_PARMS 

A pointer to the MCI_AMP_SET_PARMS data structure. This data 
structure replaces the standard default data structure, 

MCI_SET_PARMS. 

PMCI_DGV_SET_PARMS 

A pointer to the MCI_DGV_SET_PARMS data structure. This data 
structure replaces the standard default data structure, 

MCI_SET_PARMS. 
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PMCI_SEQ_SETJPARMS 

A pointer to the MCI_SEQ_SET_PARMS data structure. This data 
structure replaces the standard default data structure, 

MCI_SET_PARMS. 

PMCI_VD_SET_PARMS 

A pointer to the MCI JYD_SETJP ARMS data structure. This data struc¬ 
ture replaces the standard default data structure, MCI_SET_PARMS. 

PMCI_OVLY_SET_PARMS 

A pointer to the MCI_OVLY_SET_PARMS data structure. This data 
structure replaces the standard default data structure, 

MCI_SET_PARMS. 

PMCI_WAVE_SETJPARMS 

A pointer to the MCI_WAVE_SET_PARMS data structure. This data 
structure replaces the standard default data structure, 

MCI_SET_PARMS. 

Returns 


MCIERRJ3UCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERRJDRIVER 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_MISSING_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_MISSING_STRING_ARGUMENT 

MCIERR_INVALID_ITEM_FLAG 

MCIERR_INSTANCE_INACTIVE 

MCIERR_OUTOFRANGE 

MCIERR_UNSUPPORTED_FUNCTION 


Remarks 


The parameters and flags for this message vary according to the selected 
device. 
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MCI_SET_CUEPOINT 


MCI_SET_CUEPOINT 


This message is used to set run time cue points in the media device. 


Parameters 


ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SET_CUEPOINT_ON 

This flag is used to set a cue point at the location specified in the 
ulCuepoint field. The value in the ulCuepoint field is in the current time 
format. 

MCI_SET_CUEPOINT_OFF 

This flag is used to remove a cue point at the location specified in the 
ulCuepoint field. The value in the ulCuepoint field is in the current time 
format and must match exactly the location of a previously set cue point. 

pParam2 (PMCI_CUEPOINT_PARMS)—input 

A pointer to the MCI_CUEPOINTJPARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_ES[STANCE_INACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_lJNSUPPORTED_FLAG 

MCIERR_EWAIJD_CALLBACK_HANDLE 

MClERR_FILE_NOT_FOIJND 


MCIERR_OUT_OF_MEMORY 

MCIERR.OUTOFRANGE 

MCIERR_DUPLICATE_CUEPOESrr 

MCIERR_INVAIJD_CUEPOrNT 

MCIERR_CUEPOINT_IJMrT_REACHED 

MCIERR_MISSING_PARAMETER 


Remarks 

When the device reaches the specified points during playback, the 
CUEPOINT message is returned to the application using the window handle 
specified in the hwndCallback field. When setting a cue point on, the 
hwndCallback must contain a valid window handle. Each cue point can be 
directed to a different window handle, but only one cue point can be set at any 
given location in the media. Cue points can only be set when a device element 
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is loaded, and these are reset when a new device element is loaded. Cue points 
are persistent, that is, they remain set after they are encountered. A cue point 
is only considered to have been encountered when the device passes the cue 
point location during play back or recording, not during seek operations. 

If the length of a file cannot be determine, MCIERR_SUCCESS might be 
returned even though the specified point is out of range. 

The MM_MCICUEPOINT message is sent to the window handle specified in 
hwndCallback. An error is returned if a null or other invalid window handle is 
specified in pParam2. 
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MCI_SETIMAGEBUFFER 


MCI_SETIMAGEBUFFER 

This message writes data to the image capture buffer. The fields in the 
MCX_IMAGE_PARMS data structure are used to interpret the data. Using 
this message invalidates (or resets) the current element name or element 
HMMIO handle, since the element has been replaced by data from the applica¬ 
tion. 

Parameters 


ulParaml (ULONG)—input 

This parameter can contain the following flag: 

MCX_CONVERT 

This flag specifies that the image format conversion will be performed. 
Data is assumed to be in the device specific format. If MCI_CONVERT is 
specified, the data must be in the OS/2 uncompressed bitmap format. 

pParam2 (PMCI_IMAGE_PARMS)—input 

A pointer to the MCI_IMAGE_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR.DRIVER 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INSTANCE_INACTIVE 

MCIERR_INVALID_BUFFER 

MCIERR_OVLY_EMPTYJBUFFER 

MCIERR_INVALID_BUFFER 

MCIERR_FILE_NOT_FOUND 

MCIERR_TARGET_DEVICE_FULL 


Remarks 

The format of the image data to be set is specified by the ulPelFormat and 
usBitCount fields of the data structure pointed to by pParam2. If MCI_CON- 
VERT is specified, the data must be in OS/2 bitmap format and will be con¬ 
verted to the device-specific format. The driver expects a BITMAPHEADER2 
data structure at the beginning of the buffer, followed by any palette data, and 
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then the pel data. If MCI_CONVERT is not specified, the data will be placed 
directly into the device element buffer. If the current bits-per-pel, pixel-format, 
or MCI_CONVERT values conflict, the message will fail. 

On dual plane image capture hardware devices, the image layer content is 
assumed. Output is clipped as needed to the visible regions of the display win¬ 
dow. Conversion from OS/2 bitmap format to YUVB format is accomplished 
with an I/O procedure which can use disk space for temporary storage. 
Therefore, it is possible that errors such as MCIERR_TARGET_ 
DEVICE.FULL can occur. 
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MCLSETIMAGEPALETTE 


MC l_S ETIM AG E PALETTE 

This message sets the palette or color map that is to be used for images loaded 
with subsequent MCI_SETIMAGEBUFFER message. This message does not 
effect motion video, an image that is already displayed, or images loaded via 
the MCIJRESTORE message. This message applies only to palettized images. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain the following flag: 

MCI_SET_REGISTERED 

This flag sets the registered palette specified in the usRegisteredMap 
field. 

pParam2 (PMCI_PALETTE_PARMS)—input 

A pointer to the MCI_PALETTE_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

Remarks 

The map can either be a registered map or a map specified by the application. 
If the number of palette entries in MCX_SETIMAGEPALETTE does not 
match the number of colors in the subsequent MCXJ3ETIMAGEBUFFER 
message, the image might be displayed incorrectly. 
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MCI_SET_POSITION_ADVISE 


MCI_SET_POSITION_ADVISE 

This message is used to set periodic position change messages from the media 
device. The ulUnits field contains the interval that these messages are to be 
generated. The interval is relative to position 0 of the media. The ulUnits field 
is in current time format, but the position change messages are returned in 
MMTIME format. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SET_POSITION_ADVISE_ON 

This flag specifies that position-change advice message frequency is to be 
set to the value specified in the ulUnits field of the 
MCIJPOSITIONJPARMS data structure. 

MCI_SET_POSITION_ADVISE_OFF 

This flag disables position-change advise messages. 
pParam2 (PMCI_POSITION_PARMS)—input 

A pointer to the MCIJPOSITION_PARMS data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_INSTANCE_INACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERR_INVALID_CALLBACK_HANDLE 

MCIERR_FILE_NOT_FOUND 

MCIERR_OUT_OF_MEMORY 

MCIERR_OUTOFRANGE 

MCIERR_MISSING_PARAMETER 
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Remarks 


Setting position-change advice causes MM_MCIPOSITIONCHANGE mes¬ 
sages to be returned to the application whenever the specified media position is 
reached. The window handle specified in humdCallback field receives the posi¬ 
tion advise messages. When setting position advise on, a valid window handle 
must be specified in the humdCallback field. 

Only one position-change advice message frequency can be specified; that is, 
setting a new frequency for position-change advise messages replaces the pre¬ 
viously set position-change advise request. A device element must be loaded 
before position advise can be set, and it is reset when a new device element is 
loaded. 
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MCI_SET_SYNC_OFFSET 


MCI_SET_SYNC_OFFSET 

This message is used to specify positional offsets for devices operating in 
synchronization. 

Parameters 


ulParaml (ULONG)—input 

pParam2 (PMCI_SYNC_OFFSET_PARMS)—input 

A pointer to the MCI_SYNC_OFFSET_PARMS data structure. 


Returns 


MCIERR_SUCCESS 

MCIERR_I]WALrD_DEVICE_ID 

MCIERR_INSTANCE_INACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVAIJD_CALLBACK_HANDLE 


MCIERR.HARDWARE 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_OUT_OF_MEMORY 

MCIERR_MSSING_PARAMETER 


Remarks 


This message sets the synchronization offset for a device. When MCI_PLAY or 
MCI_SEEK messages are sent to a synchronized device group, the from posi¬ 
tion of the play for each device is biased by its synchronization offset. The syn¬ 
chronization offset is specified in the currently set device units and is 0 by 
default. 
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MCI.SPIN 


MCI_SPIN 


This message is sent to spin the player up or down. This is intended for 
videodisc players. 


Parameters 


ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SPIN_UP 

This flag starts the disc spinning. 

MCI_SPIN_DOWN 
This flag stops the disc from spinning. 
pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR.INSTANCEJNACTIVE 

MCIERR_MISSING_FIAG 

MCIERR_UNSUPPORTED_FLAG 


MCIERRJNVALID_CALLBACK_HANDLE 

MCIERR.HARDWARE 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 
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MCI_STATUS 


MCI_STATUS 

This message is used to obtain information about the current status of a device 
instance. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_STATUS_START 

Returns the starting position of the media. Specify MCI_STATUS_ 
POSITION as the status item in ulltem. 

MCI_TRACK 

A status track parameter is included in the ulTrack field of the data 
structure pointed to by pParam2. If MCI__TRACK is specified, the status 
item must be either MCI_STATUS_POSITION or 
MCI_STATUS_LENGTH. When used with MCI_STATUS_POSITION, 
the starting position of the given track, segment, or chapter is returned. 
When used with MCI_STATUS_LENGTH, the length of the given track, 
segment, element, or chapter is returned. 

MCI_STATUS_ITEM 

Indicates that the ulltem field of the data structure is identified by 
pParam2. The following constants are defined: 

MCI_STATUS_AUDIO 

One of the following status audio parameters must be included in the 
ulValue field. Other channel numbers can be specified by using the appro¬ 
priate channel number. 

MCI_STATUS_AUDIO_ALL 

Returns MCI_TRUE if all channels are on; otherwise, returns 
MCI_FALSE. This is the default value. 

MCI_STATUS_AUDIO_LEFT 

Returns MCI_TRUE if all channels are on; otherwise, returns 
MCI_FALSE. This is the default value. 
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MCI_STATUS_AUDXO_RIGHT 

Returns MCI_TRUE if all channels are on; otherwise, returns 
MCI_FALSE. This is the default value. 

MCI_STATUS_CAN_PASTE 

Returns MCX_TRUE if compatible data is to be placed in clipboard; oth¬ 
erwise, returns MCI_FALSE. This is the default value. 

MCI_STATUS__CAN_REDO 

Returns MCI_TRUE if an operation that was undone can be redone; oth¬ 
erwise, it returns MCI_FALSE. 

MCI_STATU S_C AN_UNDO 

Returns MCI_TRUE if a change has been made that can be undone; oth¬ 
erwise, it returns MCI_FALSE. 

MCI_STATUS_CLIPBOARD 

Returns MCI_TRUE if the clipboard contains information understood by 
the current device; otherwise returns MCI_FALSE. 

MCI_STATU S_CURRENT_TRACK 

Returns the current track, segment, or chapter number. 

MCI_STATUS_LENGTH 

Returns the total media length in units as specified in the MCI_SET 
message with the MCI_SET_TXME JFORMAT flag. 

Note: If the time format has been set to MCI_FORMAT_TMSF, the 
actual time value returned will be in the format 

MCI_FORMAT_MSF. 

If the media length cannot be determined because a playlist is cur¬ 
rently loaded, or for any other reason, MCIERR_INDETERMI- 

NATEJLENGTH is returned. 

MCI_STATUS_MODE 

Returns the current mode of the device, Possible values are: 

MCI_MODE_NOT_READY MCI_MODE_STOP 

MCI_MODE_PAUSE MCI_MODE_RECORD 

MCI_MODE_PLAY MCI_MODE_SEEK 
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MCI_STATUS_NUMBER_OF_TRACKS 

Returns the total number of playable tracks, segments, or chapters. 

MCI_STATUS_POSITION 

Returns the current position. 

MCI_STATUS_POSITION_IN_TRACK 

Returns the current position relative to the beginning of the current 
track, segment, or chapter. 

MCI_STATUS_READY 

Returns MCI_TRUE if the device is ready; otherwise, it returns 

MCIJFALSE. 

MCI_STATUS_MEDIA_PRESENT 

Returns MCX_TRUE or MCI_FALSE. If the device does not have remov¬ 
able media, it returns MCI_TRUE. Note that this function is only applic¬ 
able to devices which are dependent on removable media. Receiving a 
return of MCI_FALSE indicates that the device cannot function without 
inserting the media into the device. Examples of devices which might 
return MCX_FALSE to this command are CD, audio, and videodisc 
devices. 


MCI_STATUS_SPEED_FORMAT 

Returns the currently set speed format. Possible values are: 

MCI_FORMAT_PERCENTAGE MCI_FORMAT_FPS 

MCI_STATUS_TXME_FORMAT 


Returns the currently set time format. Possible values are: 


MCI_FORMAT_MILLISECONDS 

MCI_FORMAT_MMTIME 

MCI_FORMAT_MSF 

MCI_FORMAT_TMSF 

MCI_FORMAT_CHAPTERS 

MCI_FORMAT_FRAMES 

MCI_FORMAT_HMS 

MCI_FORMAT_TRACKS 

MCI_STATUS_VIDEO 


MCI_FORMAT_BYTES 

MCI_FORMAT_SAMPLES 

MCI_FORMAT_HMSF 

MCI_FORMAT_SET_SMPTE_24 

MCI_FORMAT_SET_SMPTE_25 

MCI_FORMAT_SET_SMPTE_30 

MCI_FORMAT_SET_SMPTE_30DROP 

MCI_FORMAT_SONGPTR 


Returns MCI_TRUE if video is on; otherwise returns MCI_FALSE. 
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MCI_STATU S_V OLUME 


Returns the actual volume level set in the device as a percentage of the 
maximum achievable effect. The left channel is returned in the LO word, 
and the right channel is returned in the HI word. 

MCI_STATUS_MONITOR 

Returns MCI_ON or MCI_OFF to indicate whether monitoring of the 
incoming video signal is turned on or off. 

Wave Audio Extensions 

The following additional status items apply to wave audio device drivers and 
can be specified for the ulltem field (of the data structure pointed to by 
pParam2 ) for use with the MCI_SET_ITEM flag. 

MCI_WAVE_STATU S_FORMATTAG 

Returns the currently set format tag used for playing, recording, and 
saving. 

MCI_WAVE_STATUS_CHANNELS 

Returns the currently set channel count used for playing, recording, and 
saving. 

MC I_ WAVE_STATU S_S AMPLE SPERSE C 

Returns the currently set samples per second used for playing, recording, 
and saving. 

MCI_WAVE_STATUS_AVEBYTESPERSEC 

Returns the currently set bytes per second used for playing, recording, 
and saving. Playback software can use this number to estimate required 
buffer sizes. Refer to the RIFF WAVE format documentation for more 
information. 

MCLWAVE_STATUS_BLOCKALIGN 

Returns the currently set block alignment used for playing, recording, 
and saving. 


MCI_WAVE_STATUS_BITSPERS AMPLE 

Returns the currently set bits per sample used for playing, recording, and 
saving. 
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MCI_WAVE_STATU S_LE VEL 

Returns the current record or playback level. The value is returned as an 
8-bit or 16-bit value, depending on the sample size being used. The right 
or Mono channel level is returned in the low-order word. The left channel 
level is returned in the high-order word. 


Digital Video Extensions 

The following additional status items apply to digital video devices and can be 
specified for the ulltem field (of the data structure pointed to by pParam2 ) for 
use with the MCI.SET.ITEM flag. 

MCI_DGV_STATUS_FORMATTAG 

Returns WAVE_FORMAT_PCM, the only format currently supported by 
the digital video device. If a movie is loaded that contains a format other 
than PCM, the format used in the movie will be returned. 

MCI_DGV_STATUS_DROPPED_FRAME_PCT 

Returns the percentage of dropped frames for recording or playback oper¬ 
ations. The value returned is in the range 0-100, where a value of zero 
indicates that no frame drops are occurring or have occurred and a value 
of 100 indicates that all frames are being dropped or have been dropped. 
This status value can be queried during a recording operation to obtain 
the cumulative percentage of frame drops that have occurred since record¬ 
ing began, or during playback to obtain the cumulative percentage of 
frame drops that have occurred since playback began or was resumed 
after a seek, pause, or stop. If the value is queried when the device is 
stopped, the percentage of dropped frames accumulated at the end of the 
last playback or recording operation that was performed is returned. A 
value of zero is returned if no playback or recording operations have been 
performed, the device is seeking or has been seeked, the device is paused 
or stopped, or the device is playing in scan mode. 

MC I_D GV_STATU S_S AMPLE SPE RSE C 

Returns the currently set samples per second used for playing, recording, 
and saving. 

MCI_DGV_STATUS_BITSPERSAMPLE 

Returns the currently set bits per sample used for playing, recording, and 
saving. 
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MCI_DGV_STATUS_CHANNELS 

Returns the currently set number of channels used for playing, recording, 
and saving. 

MCI JDGV_STATU S_HWND 

Returns the handle of the playback window. 

MCI_DGV_STATUS__VIDEO_COMPRESSION 

Returns the current FOURCC compression format for recording of 
motion video. Only symmetric compressors will be enabled for real-time 
recording. 

MCI__DGV__STATUS_VIDEO_QUALITY 

Returns the currently set compression quality level for recording of 
motion video. 

MCI JDGV_STATU S_MONITOR 

Returns MCI_ON or MCI_OFF to indicate whether monitoring of the 
incoming video signal is on or off. 

MCI_DGV_STATU S_HWND_MONITOR 

Returns the monitor window handle. 

mci_dgv_status_ref_interval 

Returns the value of n where n refers to a reference frame being inserted 
every nth frame. 

MCI_DGV_STATUS_IMAGE_BITSPERPEL 

Returns the pel format used for saving bit maps. 

MCI_DGV_STATU S_IMAGE_PELFORMAT 

Returns the data format used of image data for the capture device. 
Possible values are: 

MMIO_RGB_5_6_5 

Each pixel is represented by 16-bits of data as follows: 

15:5 Red level in the range 0-31 
10:6 Green level in the range 0-63 
4:5 Blue level in the range 0—31 
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MMIO_YUV_4_l_l 

This format uses 16-bits per pixel, but uses 4-pixel horizontal chromi¬ 
nance subsampling. Each pixel has a unique luminance value (Y) with a 
single chrominance value (U and V) shared by four pixels. Y, U, and V all 
7-bits of significance in this format: 

23:8 Red level in the range 0-255 

15:8 Green level in the range 0-255 

7:8 Blue level in the range 0-255 

MCIJDGV_STATUS_FORWARD 

Returns MCI__TRUE if playing forward; otherwise MCIJFALSE. 
MCI_DGV_STATUS_NORMAL_RATE 

Returns the normal-play rate of the currently loaded motion video device 
element, in the current speed format, either as a percentage or in frames 
per second. 

MC I_D GV_STATU SJVTDE 0_X_EXTENT 

Returns the horizontal (X) extent of the digital motion video image for the 
currently loaded motion video device element. 

MCI_DGV_STATUS_VIDEO_Y_EXTENT 

Returns the vertical (Y) extent of the digital motion video image for the 
currently loaded motion video device element. 

MCI_DGV_STATUS_BRIGHTNESS 

Returns the brightness level. 

MCI_DGV_STATUS_CONTRAST 
Returns the contrast level. 

MCI_DGV_STATU SJHUE 
Returns the hue level. 

MCI_DGV_STATUS_SATURATION 
Returns the saturation level. 

MCI_DGV__STATUS_RECORD_AUDIO 

Returns the MCI_ON or MCI_OFF to indicate whether recording the 
audio soundtrack has been turned on or off. 
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MCI_DGV_STATUS_SPEED 

Returns the digital video speed in frames per second. 

MCI_DGV_STATUS_TRANSPAIlENT_COLOR 

Returns a value representing the transparent color used as the chroma¬ 
key on video overlay hardware. 

MCI_DGV_STATUS_VIDEO_RECORD_FRAME_DURATION 

Returns the frame rate for recording as the time duration of each frame 
in microseconds. 

Video Overlay Extensions 

The following additional items apply to video overlay devices and can be speci¬ 
fied for the ulltem field (of the data structure pointed to by pParam2) for use 
with the MCI_SET_ITEM flag: 

MCI_0 VLY_STATU S_HWND 

Returns the handle of the playback window. 

MCI_OVLY_STATUS_IMAGE_COMPRESSION 

Returns the compression format of the currently loaded bit map/image. 

MCI_OVLY_STATUS_BITSPERPEL 

Returns the number of bits per pel of the currently loaded bitmap/image. 
Return values include: 

• MCI_IMG_P ALETTE 

• MCI_IMGJRGB 

• MCI_IMG_YUV 

MCI_OVLY_STATU S_PELFORMAT 

Returns the pel format of the currently loaded bitmap/image. 

MCI_OVLY_STATUS_BRIGHTNESS 

Returns the brightness level. 

MC I_0 VL Y_STATU S_C ONTRAST 

Returns the contrast level. 

MC I_0 VL Y_STATU S_HUE 

Returns the hue level. 
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MCI_OVLY_STATUS_SATURATION 
Returns the saturation level. 

MCI_OVLY_STATU S_SHARPNE SS 
Returns the sharpness level. 

MCI_OVLY_STATUS_TRANSPARENT_COLOR 

Returns a value representing the RGB value or palette value, which spec¬ 
ifies the transparent color. RGB values are returned as a 32-bit RGB data 
item. 

MC I_0 VLY_STATU S_TRAN SPARENT_TYPE 

Returns a value representing information to assist in interpreting the 

MCI_OVLY_STATUS_TRANSPARENT_COLOR. Return values 
include: 

• MCI_IMG_P ALETTE 

• mci_img_rgb 

• MCI_IMG_YUV 

MC I_0 VLY_STATU S_GRE Y SCALE 

Returns MCI.ON or MCI.OFF. 

MCI_OVLY_STATUS_IMAGE_COMPRESSION 

Returns the compression type for saving still images. 

MCI_OVLY_STATU S_IMAGE_BITSPERPEL 

Returns the number of bits per pel used for the image file to be saved. 

MCI_OVLY_STATUS_IMAGE_PELFORMAT 

Returns the pel format used for saving bitmaps. 

MCI_OVLY_STATUS_IMAGE_QUALITY 

Returns the quality of the image in the element buffer. 

MCI_OVLY_STATU S_IMAGE_X_EXTENT 

Returns the width, in pels, of the image in the element buffer. 

MCI_OVLY_STATUS_IMAGE_Y_EXTENT 

Returns the height, in pels, of the image in the element buffer. 
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MCI_OVLY_STATU S_IMAGE_FILE_FORMAT 

Returns the format in which an image capture will be stored when saved. 
Amplifier Mixer Extensions 

The following additional status items apply to amplifier mixer devices and can 
be specified for the ulltem field (of the data structure pointed to by pParam2) 
for use with the MCI_SET_ITEM flag: 

MCI_AMP_STATU S_B ASS 

Returns bass level for this mixer channel as a percentage of the maxi¬ 
mum achievable bass effect. 

MCI_AMP_STATUS_TREBLE 

Returns treble level for this mixer channel as a percentage of the maxi¬ 
mum treble effect. 

mci_amp_status_balance 

Returns a balance level for this mixer channel. A value of zero indicates 
full left balance while 100 indicates full right balance, and 50 indicates 
neutral balance. 

MCI_AMP_STATUS_PITCH 

Returns the pitch as a percentage of the maximum achievable effect. 

MCI_AMP_STATUS_GAIN 

Returns the current gain setting as a percentage of the maximum achiev¬ 
able effect. 

CD Audio Extensions 

The following additional status items apply to CD audio device drivers and can 
be specified for the ulltem (field of the data structure pointed to by pParam2 ) 
for use with the MCI_SET_ITEM flag: 

MCI_CD_STATUS_TRACK_TYPE 

Returns one of the following: 


MCI_CD_TRACK_AUDXO 
MCI_CD_TRACK_DATA 
MCI CD TRACK OTHER 
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MCI_CD_STATUS_TRACK_COPYPERMITTED 

Returns MCI_TRUE if digital copying is permitted; otherwise, it returns 

MCI_FALSE 

MCI_CD_STATUS_TRACK_CHANNELS 

Returns the number of audio channels on the track. 

MCI_CD_STATUS_TRACK_PREEMPHASIS 

Returns MCI_TRUE if the track was recorded with pre-emphasis; other¬ 
wise, it returns MCI_FALSE. 

Note: When used with the MCI_TRACK flag, these items return the sta¬ 
tus information of the specified track instead of the current track. 

CD/XA Extensions 

The following extensions apply to CDXA devices and can be specified for the 
ulltem field of the data structure pointed to by pParam2 : 

MCI_CDXA_STATUS_CHANNEL 

Returns the destination of the data in channel ulChannel. Returns one of 
the following: 

MCI_CDXA_AUDIO_DEVTCE MCI_CDXA_VIDEO_BUFFER 

MCI_CDXA_AUDIO_BUFFER MCI_CDXA_DATA_BUFFER 

MCI_CDXA_NONE 


Sequencer Extensions 


The following additional status items apply to MIDI sequencer devices and can 
be specified for the ulltem field (of the data structure pointed to by pParam2 ) 
for use with the MCI_SET_ITEM flag: 

MCI_SEQ_STATUS_DIVTYPE 

Returns one of the following values as the current division type of a 
sequence: 

MCI_SEQ_DIV_PPQN MCI_SEQ_DIV_SMPTE_25 

MCI_SEQ_DIV_SMPTE_24 MCI_SEQ_DIV_SMPTE_30 

MCI_SEQ_DIV_SMPTE_30DROP 

MCI_SEQ_STATUS_MASTER 

Returns the synchronization type used for master operation. 
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MCI_SEQ_STATUS_OFFSET 

Returns the current SMPTE offset of a sequence. 

MCI_SEQ_STATUS_PORT 

Returns the MIDI device ID for the current port used by the sequence. 

MCI_SEQ_STATUS_SLAVE 

Returns the synchronization type used for slave operation. 

MCI_SEQ_STATUS_TEMPO 

Returns the current tempo of a MIDI sequence in beats-per-minute for 
PPQN files, or frames-per-second for SMPTE files. Currently this func¬ 
tion is unsupported by the IBM sequencer. 

Videodisc Extensions 

The following additional status items apply to videodisc drivers and can be 
specified for the ulltem field (of the data structure pointed to by pParam2) for 
use with MCI_SET_ITEM flag: 

MCI_VD_STATUS_SPEED 

Returns the speed in the currently set speed format. 

MCI_VD_STATUS_FORWARD 

Returns MCI_TRUE if playing forward; MCI_FALSE otherwise. 

MCI_VD_MEDIA_TYPE 
Returns one of the following: 

• MCI_VD_MEDIA_CAV 

• MCI_VD_MEDIA_CLV 

• MCI_VD_MEDIA_OTHER 
MCI_VD_STATUS_SIDE 

Returns 1 or 2 to indicate which side of the disc is loaded. 
MCI_VD_STATUS_DISC_SIZE 
Returns the size of the loaded disc in inches (8 or 12). 
pParam2 (PMCI_STATUS_PARMS)—input 

A pointer to the MCI_STATUS_PARMS data structure. 
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Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERRJDRIVER 


MCIERR_INVALID_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_INVALID_ITEM_FLAG 


Remarks 

The parameters and flags for this message vary according to the selected 
device. All devices support this message and the applicable status items for 
each device are listed with each parameter. See the MCI_SET message for the 
values which can be returned for each particular item. 
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MCI_STEP 


MCI_STEP 

This message is sent to step the player. 

Parameters 


ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_STEP_FRAMES 

This flag is used to set a step frames parameter. This provides step for¬ 
ward support. 

MCI_STEP_REVERSE 

This flag is used to set a steps in reverse parameter. 
pParam2 (PMCI_STEP_PARMS)—input 

A pointer to the MCI_STEP_PARMS data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_INVAIJD_DEVICE_ID 

MCIERRJCMSTANCEJNACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVALJD_CAT J ,BACK_HANDLE 

MCIERR_HARDWARE 


MCIERR_UNSUPPORTED_FUNCnON 

MCIERR_INVAIJD_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_INVALID_ITEM_FLAG 

MCIERR_MISSING_ITEM 

MCIERR_MISSING_PARAMETER 


Remarks 


This step can be sent for either forward-frame or reverse-frame operation. 
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MCI_STOP 


MCI_STOP 

This message is sent to stop playback or recording. 

Parameters 


ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_INVALID_DEVICE_ID 

MCIERR_INSTANCE_rNACTIVE 

MCIERR_MISSING_FLAG 

MCIERR_UNSUPPORTED_FLAG 

MCIERR_INVALID_CAIJ,BACK_HANDLE 

MCIERR_HARDWARE 


MCIERR_UNSUPPORTED_FUNCTION 

MCIERR_EWAIJD_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCTERRTNV AT JD TTEMJFT AG 

MCIERR_MISSING_rrEM 

MCIERR_MISSING_PARAMETER 


Remarks 


If playback or recording is to be restarted with minimal latency, MCI_PAUSE 
should be used. 
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MCI_SYSINFO 


MCLSYSINFO 

This message returns information about Media Control devices and device 
instances. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

MCI_SYSINFO_INSTALL_NAME 

This flag returns the name used to install the device. 

MCI_SYSINFO_QUANTITY 

This flag sets the media to return the number of devices of the given type. 
If the MCI_SYSINFO_OPEN flag is set, the number of open devices is 
returned. 

MCI_SYSINFO_NAME 

This flag is used to select a number of device ordinal parameters. The 
media returns the name(s) of a device that satisfies the query. If more 
than one name is returned, then the names are separated by a single 
blank, and the string is null terminated. 

MCI_SYSINFO_OPEN 

This flag returns the number of name of open devices. 

MCI_SYSINFO_ITEM 

This flag indicates that the ulltem field contains a constant that indicates 
the desired MCI_SYSINFO action as indicated by one of the following 
values: 

MCI_SYSINFO_INSTALL_DRIVER 

This message creates or updates a logical device entry in the INI file. The 
pSysInfo field points to the MCI_SYSINFO_LOGDEVICE structure. 
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MCI_SYSINFO_QUERY_DRIVER 

This message queries the information for the driver indicated in the 
szInstallName field, the pSysInfoParm field points to the MCIJSYSIN- 
FOJLOGDEVICE structure. The driver becomes active the next time 
MMPM/2 is started. 

MCI_SYSINFO_INIJLOCK 

Writes out and then locks the MMPM/2 file from updates. The driver 
becomes active the next time MMPM/2 is started. 

MCI_SYSINFO_DELETE_DRIVER 

This message removes the specified driver from the INI file. The 
pSysInfoParm field points to the install name. 

MCI_SYSINFO_SET_PARMS 

This message sets the device specific parameters for a particular device. 
Device specific parameters should be printable ASCII characters only so 
that response files can be supported. The pSysInfoParm fields points to 

the MCI_SYSINFO_DEVPARAMS structure. 

MCI_SYSINFO_QUERY_PARMS 

This message retrieves the device specific parameters for a particular 
device. The pSysInfoParm field points to the MCI_SYSINFO_DEV- 
PARAMS structure. 

MCI_SYSINFO_SET_CONNECTORS 

This message sets the logical connector information for a particular 
device. The connector array defined by ConnectorList is a list of the con¬ 
nectors in sequential order. For example, ConnectorList [0] is connector 
index 1. The pSysInfoParm field points to the MCI_SYSINFO_CON- 
PARAMS structure. 

MCI_SYSINFO_QUERY_CONNECTORS 

This message retrieves the device connector information for a particular 
device. The pSysInfoParm field points to the MCI_SYSINFO_CON- 
PARAMS structure. 

MCI_SYSINFO_SET_EXTENSIONS 

This message sets the file extension associated with a particular device. 
The pSysInfoParm field points to the MCI.SYSINFOJEXTENSION 
structure. Extensions are unique across installation names. That is, no 
two installation names can have the same extension. 
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MCI_SYSINFO_QUERY_EXTENSIONS 

This message queries the file extensions associated with a particular 
device. The pSysInfoParm field points to the MCI_SYSINFO_EXTEN- 
SION structure. 

MCI_SYSINFO_SET_TYPES 

This message sets the extended type attribute associated with a particu¬ 
lar device. The pSysInfoParm field points to the MCI_SYSINFO_TYPES 
structure. 

MCI_SYSINFO_QUERY_TYPES 

This message queries the extended type attributes associated with a par¬ 
ticular device. The pSysInfoParm field points to the 

MCI_SYSINFO_TYPES structure. 

MCI_SYSINFO_SET_ALIAS 

This message associates an alias to a particular device. The 
pSysInfoParm field points to the MCI_SYSINFO_ALIAS structure. 

MCI_SYSINFO_QUERY_NAMES 

This message queries the names associated with a particular device. This 
message will accept any of the three types of names or device type and 
device ordinal, and it will fill in the remaining structure if possible. If the 
device type is given, and 0 is given for the device ordinal, then the first 
device of that type is returned. Only one non-null name or 0 in device type 
field on input is allowed. The pSysInfoParm field points to the MCI_SYS- 
XNFO_QUERY_NAME structure. 

MCI_SYSXNFO_SET_DEFAULT 

This message sets a device as the default for its device type. If another 
device is already the default for this device type, then it will be super¬ 
seded by the dew device. The pSysInfoParm field points to the MCI_SYS- 
XNFO_DEFAULTDEVTCE structure. 

MCI_SYSINFO_QUERY_DEFAULT 

This message queries the default device for a given device type. If no 
explicit default exists, then the first device of the indicated type is implic¬ 
itly the default. The pSysInfoParm field points to the 

MCI_SYSINFO_DEFAULTDEVICE structure. 

P Param2 (PMCI_SYSINFO_PARMS)—input 

A pointer to the MCX_SYSXNFO_PARMS data structure. 
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Returns 


MCIERR_SUCCESS MCIERR_INVAIJD_FLAG 

MCIERR_MISSEVG_FLAG MClEIRt_FLAGS_NOT_COIVIPATIBLE 

MCIERR_UNSUPPORTED_FLAG MCIERR_MISSING_PARAMETER 

MCIEmt_INVALID_CAIJ,BACK_HANDLE MCIERR_INVALID_BUPFER 
MCIERR_DUPLICATE_ALIAS MCIERR_DEVICE_NOT_FOlJND 

MCIERR_DUPLICATE_EXTENSION MCIERRJPt TPT JCATE_EA 

MCIERR_NODEFAULT_DEVICE 

Remarks 

The MCI_NOTIFY flag is not valid for this message. 

The usDeviceType of the MCI_SYSINFO_PARMS data structure is used to 
indicate the device type of the query. Specifying MCI_ALL_DEVICE_XD as 
the usDeviceld parameter, the Media Control Interface returns information on 
all devices open by the current process. If MCI_ALL_DEVICE_ID and 
MCX_SYSINFO_NAME are specified together then the ulNumber field of the 
MCI_SYSINFO_PARMS data structure is ignored and names for all devices 
is returned. The names will be returned separated by a single blank and null 
terminated. 

The MCI_SYSINFO ulterm actions are intended to be used by applications 
that need to update the MMPM2.INI file, such as install and setup. The 
MCI.SYSXNFO ulterm actions MCX_SYSINFO_INSTALL_DRIVER and 
MCI_SYSINFO_DELETE will not take effect until MMPM/2 is unloaded and 
then loaded again. All other MCX_SYSINFO ulterm actions take effect during 
the current session. 
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MCIJJNDO 


MCLUNDO 

This message undoes the operation most recently performed by cut, paste, or 
delete. 

Parameters 

ulParaml (ULONG)—input 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 

Returns 


MCIERRJSUCCESS MCIERR_INSTANCE_INACTTVE 

MCIERR_INVALID_DEVICE_ID MCIERR_INVAIJDD_CALLBACK_HANDLE 
MCIERR_INVALID_FLAG MCIERR_CANNOT_UNDO 


Remarks 


After an undo operation, the media position is at the beginning of the media. 
Undo is unlimited, however, after a save, any previous editing actions (such as 
cut, delete, paste) are cleared and cannot be undone. If there are no more possi¬ 
ble actions to be undone (the file is in the state where the last change was 
made) then MCIERR_CANNOT_UNDO is returned. If undo interrupts an in¬ 
progress operation, the command is aborted, and an aborted notification mes¬ 
sage is sent. Not all devices support this command. Use the MCI_GETDEV- 
CAPS message to determine whether the device supports MCI_UNDO. 
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MCI_UNFREEZE 


MCIJJNFREEZE 

This message restores motion to an area of the display frozen with 

MCI.FREEZE or MCI_RESTORE. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

Video Overlay Extensions 

MCI_OVLY_FREEZE_RECT 

The rect field of the data structure identified by pParam2 contains a valid 
rectangle. If the MCI_OVLY_FREEZE_RECT parameter is not speci¬ 
fied, the entire video destination rectangle is unfrozen. 

mci_ovly_freeze_rect_outside 

Indicates the area outside the specified rectangle is to be unfrozen. 
pParam2 (PMCI_OVLY_RECT_PARMS)—input 

A pointer to the MCI_OVLY_RECT_PARMS data structure. 

Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR.DRIVER 


MCIERR_INVALID_FLAG 

MCIERR.INSTANCEJNACTIVE 

MCIERR_OVLY_INVALID_RECT 

MCIERR_OVLY_NOT_AVAILABLE 


Remarks 


Areas outside the current video destination region will be unaffected. Multiple 
MCI_FREEZE and MCI_UNFREEZE messages can be issued sequentially to 
build up a complex region of frozen and unfrozen video. 
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MCI_WHERE 


MCI.WHERE 

This message returns the source and destination rectangles, and the location of 
the video window. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

Digital Video Extensions 

MCI_DGV_WHERE_DESTINATION 

This flag indicates that the destination display rectangle should be 
returned in the rc field. 

MCI_DGV_WHERE_SOURCE 

This flag indicates that the video source rectangle should be returned in 
the rc field. 

MCI_DGV_WHERE_AD JUSTED 

Used with either MCI_DGV_WHERE_SOURCE and 
MCI_DGV_RECORD or MCI_DGV_WHERE_DESTINATION and 
MCI_DGV_RECORD. When MCI_DGV_WHERE_ADJUSTED is spec¬ 
ified, these commands return the coordinates that will actually be used to 
record a movie or to get an image buffer based on what was set with 
MCIJPUT in combination with the capabilities of the capture hardware. 

MCI_DGV_WHERE_WINDOW 

This flag indicates that the current location of the video window relative 
to its parent should be returned in the rc field. 

MCI_DGV_MONITOR 

This flag indicates that the window size and position for the monitor 
window. 

mci_dgv_record 

This flag indicates that the source and destination rectangles for the 
video capture. 
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Video Overlay Extensions 

MCI_OVLY_WHERE_DESTINATION 

This flag indicates that the destination display rectangle should be 
returned in the rc field. 

MCI_OVLY_WHERE__SOURCE 

This flag indicates that the video overlay source rectangle should be 
returned in the rc field. 

MCI_OVLY_WHERE_WINDOW 

This flag indicates that the current location of the video window relative 
to its parent should be returned in the rc field. 

pParam2 (PMCI_GENERIC_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVTCE_ID 

MCIERR_MISSING_PARAMETER 


MCIERR_DRIVER 

MCIERR_INVALID_FLAG 

MCIERR_FLAGS_NOT_COMPATIBLE 

MCIERR_INSTANCE_INACTIVE 


Remarks 


A pointer to the rectangle is returned in the rc field. 
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MCI_WINDOW 


MCI.WINDOW 

This message specifies the window and the window characteristics that a 
graphic device should us for display. 

Parameters 

ulParaml (ULONG)—input 

This parameter can contain any of the following flags: 

Digital Video Extensions 

MCI__DGV_WINDOW_HWND 

This flag indicates the handle of the application window to be used for 
video is included in the hwndDest field. 

MCI_DGV_WINDOW_STATE 

This flag indicates that the usCmdShow field contains one of the follow¬ 
ing parameters for setting the window state: 

SWP_ACTIVATE SWPJVLAXIMIZE SWP_SHOW 

SWP.DEACTIVATE SWP.MINIMIZE 

SWP.HIDE S WP_RE STORE 

The MCI_DGV_WINDOW_STATE flag will not affect an application 
supplied alternate video window. 

MCI_DGV_WINDOW_TEXT 

This flag indicates that the pszText field contains a pointer to a buffer 
containing the caption used for the window. 

MCI_DGV__WINDOW_DEFAULT 

This flag indicates that the default video window should be used as the 
target for video. 

MCI_DGV_MONITOR 

This flag indicates functions associated with the MCI_WINDOW mes¬ 
sage are to be applied to the monitor window. The monitor window output 
can be directed to an application specified window in the same manner as 
video playback. 
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Video Overlay Extensions 

MCI_OVLY_WINDOW_HWND 

This flag indicates the handle of the application window to be used for 
video is included in the humdDest field. 

MCI_OVLY_WINDOW_STATE 

This flag indicates that the usCmdShow field contains one of the follow¬ 
ing parameters for setting the window state: 

SWP.ACTIVATE SWP.MAXIMIZE SWP_SHOW 

SWP.DEACTIVATE SWP.MINIMIZE 

SWP.HIDE S WP_RE STORE 

The MCI_OVLY_ WIND OW_ST ATE flag will not affect an application sup¬ 
plied alternate video window. 

MCI_OVLY_WINDOW_TEXT 

This flag indicates that the pszText field contains a pointer to a buffer 
containing the caption used for the window. 

MCI_OVLY_WINDOW_DEFAULT 

This flag indicates that the default video window should be used as the 
target for video. 

pParam2 (PMCI_DGV_WINDOW_PARMS)—input 

A pointer to the default media control interface parameter data structure. 


Returns 


MCIERR.SUCCESS 

MCIERR_OUT_OF_MEMORY 

MCIERR_INVALID_DEVICE_ID 

MCIERR_MISSING_PARAMETER 

MCIERR_DRIVER 


MCIERR_INVALID_FLAG 
MCIERR_MISSING_FLAG 
MC IERR_FLAGS_N OT_C OMP ATIBLE 
MC IERR_IN STAN CE_INACTIVE 


Remarks 


By default, video devices create a window when an application opens the 
device, but the window is not displayed until the devices receive a window 
state show command or a play command. Applications can send the 
MCI_WINDOW message to tell a video device to use an application window 
instead of the default window to display video. Applications that supply win¬ 
dow handles should be prepared to update an invalid rectangle on the window. 
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Several flags are provided to allow users to manipulate the window. Because 
MCI_STATUS can be used to obtain the current window handle, programmers 
might choose to use the standard window APIs instead. The flags are provided 
to allow applications that use the string interface to perform standard opera¬ 
tions. 

Support of this message by a device is optional. The parameters and flags for 
this message vary according to the selected device. 
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MCI DATA STRUCTURES 


MCI_AMP_OPEN_PARMS 

This structure contains the fields for the MCI_OPEN message used with 
amplified mixer devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

usDevicelD (USHORT)—input 

The device ID returned to the user. 

usReservedO (USHORT)—input 

Reserved field. 

pszDeviceType (PSZ)—input 
The type of the device. 
pszElementName (PSZ)—input 
The media element or NULL. 
pszAlias (PSZ)—input 
An optional device alias. 
pDevDataPtr (PVOID)—input 

A pointer to the amplifier mixer device data structure or NULL. 
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MC LC APTU RE_PARMS 

This structure contains the fields for the MCI_CAPTURE message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCX_NOTIFY flag is specified. 

rect (RECTL)—input 

A rectangle specifying the window subregion to be captured. 

MCI_CDXA_SET_PARMS 

This structure contains the fields for the MCI_SET message used with CD/XA 
devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTimeFormat (ULONG)—input 

The time format to be used by the device. 

ulSpeedFormat (ULONG)—input 

The speed format to be used by the device. 

ulAudio (ULONG)—input 

The channel number for the following operations. 

• MCI_SET_AUDIO_LEFT 

• MCI_SET_AUDIO_RIGHT 

• MCI_SET_AUDIO_ALL 
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ulLevel (ULONG)—input 

Audio volume level as a percentage of maximum. 
ulOver (ULONG)—input 

Delay time for vectored change in milliseconds, 
ulltem (ULONG)—input 
Item field for set item flag. 
ulValue (ULONG)—input 

Value associated with item flag. 
ulChannel (ULONG)—input 

Specifies which CD/XA channel to set. 
pPlayList (PVOID)—input 

Specifies a pointer to the memory playlist. 
ulPlayListSize (ULONG)—input 
Size of the memory playlist. 


MCI_CONNECTION_PARMS 

This structure contains the fields for the MCI_CONNECTION message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulConnectorType (ULONG)—input 

If specified, this indicates that ulConnectorlndex is relative to the specified 
connector type. Otherwise, ulConnectorlndex is an absolute index. 

ulConnectorlndex (ULONG)—input 

Connector index for the primary device. The interpretation of the connector 
index depends on the ulConnectorType field. If the 
MCX_CONNECTOR_INDEX is not specified, then the first connector is 
assumed. 
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pszAlias (PSZ)—input 

The alias name to set for the secondary device. If the alias already exists for 
another device, the error MCIERR_DUPLICATE_ALIAS is returned. If 
the connected to device already has an alias the error MCIERR_CAN- 
NOT_ALIAS is returned. 

usToDevicelD (USHORT)—input 

The device ID of the secondary device to which the connection is being estab¬ 
lished. 

usReservedO (USHORT)—input 

Reserved for future use. Must be zero. 
ulReservedl (ULONG)—input 

Reserved for future use. Must be zero. 
ulReserved2 (ULONG)—input 

Reserved for future use. Must be zero. 
ulReserved (ULONG)—input 

Reserved for future use. Must be zero. 


MCI_CONNECTIORINFO_PARMS 

This structure contains the fields for the MCI_CONNECTORINFO message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulReturn (ULONG)—input 

Return information. 

ulDeviceTypelD (ULONG)—input 

Indicates the Media Control Interface device type for which connector infor¬ 
mation is to be returned. 

ulConnectorType (ULONG)—input 

If specified, indicates that ulConnectorlndex is relative to the specified con¬ 
nector type. Otherwise, ulConnectorlndex is an absolute index. 
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ulConnectorlndex (ULONG)—input 

Connector index for the primary device. The interpretation of the connector 
index depends on the ulConnectorType field. If the 
MCI_CONNECTOR_INDEX is not specified then the first connector is 
assumed. 

ulToConnectorType (ULONG)—input 

Indicates the connector type to test if MCI__QUERY_VALID_CONNEC- 
TION is specified. Returns MCI_TRUE if the connector type specified in 
ulConnectorType and ulToConnectorType are compatible, otherwise returns 

MCI_FALSE. 


MCI_CUEPOINT_PARMS 

This structure contains the fields for the MCI_CUEPOINT message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulCuepoint (ULONG)—input 

The cue point location in MMTIME units. 

usUserParm (USHORT)—input 

The user parameter returned for the cue point asynchronous notification 

(MM.MCICUEPOINT) message. 

usReservedO (USHORT)— input 


Reserved. 
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MCI_DEFAULT_CONNECTION_PARMS 

This structure contains the fields for the MCI_DEFAULT_CONNECTION 
message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

pszDevice (PSZ)—input 

Device name. 

ulConnectorType (ULONG)—input 

If specified, indicates that ulConnectorlndex is relative to the specified con¬ 
nector type. Otherwise, ulConnectorlndex is an absolute index. 

ulConnectorlndex (ULONG)—input 

Connector index for the primary device. The interpretation of the connector 
index depends on the ulConnectorType field. If the 
MCI_CONNECTOR_INDEX is not specified, then the first connector is 
assumed. 

pszToDevice (PSZ)—input 

If MCI_MAKE_CONNECTION is specified, this field indicates the device 
name to which the connection is to be established. If MCI_QUERY_CON- 
NECTION is specified and a connection exists, this field returns the device 
name to which the connection exists. If no connection exists, this field is set 
to NULL on return, and the error MCIERR_NO__CONNECTION is 
returned. 

ulToConnectorType (ULONG)—input 

If MCI__CONNECTOR_TYPE is specified, this field indicates the connector 
type of the connector on the other device for this connection. This field indi¬ 
cates the connector type on input if MCI_MAKE_CONNECTION is speci¬ 
fied, and indicates the connector type on output if MCI_QUERY_CONNEC- 
TION is specified. 
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ulToConnectorXndex (ULONG)—input 

Specifies the connector number of the connector on the other device for this 
connection. This value is specified on input when establishing a connection, 
and it is returned on output when querying a connection. This connector 
index is either absolute or relative, depending on whether or not the 

MCI_CONNECTOR_TYPE flag is set. If MCI_CONNECTOR_INDEX is 

not specified, then 1 is assumed. 


MCI_DEVICESETTINGS_PARMS 

This structure contains the fields for the MCI_DE VICE SETTINGS message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

hwndNotebook (HWND)—input 

Handle to notebook window. 

usDeviceType (USHORT)—input 

Device type. 

pszDeviceName (PSZ)—input 
Logical device name. 


MCI_DGV_PLAY_PARMS 

This structure contains the fields for the MCI_PLAY message for digital video 
devices. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 
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ulFrom (ULONG)—input 
The position to play from. 
ulTo (ULONG)—input 
The position to play to. 
ulSpeed (ULONG)—input 

The play rate in frames per second. 


MCI_EDIT_PARMS 

This structure contains the fields for the MCX_CUT, MCI_COPY and 
MCI_PASTE messages. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTXFY flag is specified. 

ulStructLen (ULONG)—input 

Length of the structure. 

ulFrom (ULONG)—input 

Beginning point of range in device element. 

ulTo (ULONG)—input 

Ending point of range in device element. 

pBuff (PVOID)—input 

Pointer to a application supplied buffer; otherwise, NULL to indicate clip¬ 
board. 

ulBufLen (ULONG)—input 
Length of application buffer. 
pHeader (PVOID)—input 

Header that describes the application supplied buffer. 
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MCI_ESCAPE_PARMS 

This structure contains the fields for the MCI_ESCAPE message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCX_NOTIFY flag is specified. 

pszCommand (PSZ)—input 

A pointer to a null-terminated buffer that contains the command to send to 
the device. 


MCI_GENERIC_PARMS 

This structure contains the fields for messages that have empty parameter 
lists. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 


mci_getdevcaps_parms 

This structure contains the fields for the MCI_GETDEVCAPS message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 
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ulReturn (ULONG)—input 

The format of the ulReturn value in this structure is defined by the high 
order word of the value returned by the mciSendCommand API. This 
value is used by the mciSendString API to determine how to convert the 
ulReturn value to string form. See the MCIDRV.H header file for a list of 
possible format values. 

ulltem (ULONG)—input 

A ULONG identifying an item field for MCI_GETDEVCAPS item to query. 
usMessage (USHORT)—input 

The message ID being queried if MCI_GETDEVCAPS is specified. 
usReservedO (USHORT)—input 
Reserved. 


MC l_GROU P_PARMS 

This structure contains the fields for the MCI_GROUP message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI__NOTIFY flag is specified. 

usGroupID (USHORT)—input 

This field contains the unique identification number used to distinguish one 
particular group from other groups/devices/instances. On an 
MCI_GROUP_MAKE, this field will be filled in and returned to the caller. 
On MCI_GROUP_DELETE, this field will be used to reference the specific 
group to delete if no MCI_GROUP_ALIAS flag is specified. 

usReservedO (USHORT)—input 

Reserved. 

ulStructLength (ULONG)—input 

This is the length of the structure in ULONGs from the first field 
C hwndCallback ) to the last field ( paulDevicelD ). If the structure changes in 
the future, the Media Device Manager can process the data according to this 
value. 
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usMasterlD (USHORT)—input 

This field is currently unused. It will be used in the future for group syn¬ 
chronization. 

usReservedl (USHORT)—input 
Reserved. 

pszGroupAlias (PSZ)—input 

A pointer to a ASCIIZ string containing the alias name for this particular 
group. This filed is processed only when the MCI_GROUP_ALIAS and 
MCI_GROUP_MAKE flags are set. 

ulNumDevices (ULONG)—input 

Number of devices in group. 

paulDevicelD (PULONG) 

This field contains an array of device Ids in the group. 


MCIJMAGE_EDIT_PARMS 

This structure contains the fields for the MCI_CUT, MCI_COPY, and 
MCI_PASTE message for video devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

uIStructLen (ULONG)—input 

Structure length. 

ulXPos (ULONG)—input 

Beginning point of the range. 

ulYPos (ULONG)—input 

Ending point of the range. 

ulWidth (ULONG)—input 

Width of the image. 
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ulLength (ULONG)—input 
Length of the image. 
pBuff(PVOID)— input 

Pointer to a application supplied buffer; otherwise, NULL to indicate clip¬ 
board. 

ulBufLen (ULONG)—input 

Length of the application buffer. 


MCIJMAGE_PARMS 

This structure contains the fields for the MCI_GETIMAGEBUFFER and 
MCI_SETIMAGEBUFFER messages. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulPelFormat (ULONG)—input 

The format of the data in the capture device element. If MCI_CONVERT is 
true, this field contains one of the supported OS/2 2.0 bitmap formats. If 
MCI_CONVERT is false, this field contains a device-specific format. The 
specified format must be compatible with the value in the usBitCount field. 

Possible values include: 

MCI_IMG_P ALETTE 

MCI_IMG_RGB 

MCI_IMG_YUV 

This field is input for MCI_SETIMAGEBUFFER, and output for 
MCI_GETIMAGEBUFFER. If a palettized format is requested, the cur¬ 
rently defined palette will be supplied by MCI_SETIMAGEPALETTE. 

usBitCount (USHORT)—input 

Number of bits per pixel for the data in the capture device element. If 
MCI_CONVERT is true, this field contains a value for one of the supported 
OS/2 bitmap pixel formats (1, 4, 8, or 24). If MCI_CONVERT is false, this 
field contains a device specific value. 
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usReserved (USHORT)—input 
Reserved. 

ullmageCompression (ULONG)—input 
Compression type of data in buffer. 
reRect (RECTL)—input 

A window rectangle of the area to read or write. 
pPelBuffer (PVOID)—input 

If pPelBuffer is equal to 0 on a MCI_GETIMAGEBUFFER message, the 
message will be considered a query for the buffer length and attributes of 
the current image element. 

ulBufferHeight (ULONG)—input 

Height of the buffer specified by pPelBuffer. 

ulBufferWidth (ULONG)—input 

Width of the buffer specified by pPelBuffer. 

ulBufLen (ULONG)—input 

Length of buffer specified by pPelBuffer. 


MCIJNFO_PARMS 

This structure contains the fields for the MCI_INFO message used with 
amplified mixer devices. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

pszReturn (PSZ)—input 

A pointer to a application supplied buffer for the return string. 
ulRetSize (ULONG)—input 

The size, in bytes, of the buffer for the return string. Upon return, it con¬ 
tains the number of bytes the string required. If the size was greater or 
equal to this size, the entire string will be returned; otherwise, only what 
will fit is returned. 
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MCI_LOAD_PARMS 

This structure contains the fields for the MCI_LOAD message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

pszElementName (PSZ)—input 

The media element to be loaded. 


mci_masteraudio_parms 

This structure contains the fields for the MCI_MASTERAUDIO message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulReturn (ULONG)—input 

Master volume level or speaker/headphone on/off 

(MCI_TRUE/MCI_FALSE) state if MCI.QUERYCURRENTSETTING or 
MCI_QUERYSAVEDSETTING is specified. 

ulMasterVolume (ULONG)—input 

The master volume level setting. If MCI_MASTERVOL is specified, this 
field contains the master volume as a percentage. If a value greater than 
100 is given, 100 will be used, and no error will be returned. 



APPENDIX A: Media Control Interface 533 


MCI_OPEN_PARMS 

This structure contains the fields for the MCI_OPEN message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

usDevicelD (USHORT)—input 

The device ID returned to the user. 

usReservedO (USHORT)—input 

Reserved field. 

pszDeviceType (PSZ)—input 
The type of the device. 
pszElementName (PSZ)—input 
The media element or NULL. 
pszAlias (PSZ)—input 
An optional device alias. 


MCI_PALETTE_PARMS 

This structure contains the fields for the MCI_GETIMAGEPALETTE and 
the MCI_SETIMAGEPALETTE messages. 

Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCIJVOTIFY flag is specified. 

usRegisteredMap (USHORT)—input 

Registered palette number. 
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usReservedO (USHORT)—input 
Reserved. 

ulPalEntries (ULONG)—input 

The number of RGB entries to be set on an MCI_SETIMAGEPALETTE 
message, or the number of entries placed in pPalette on a MCI_GETIM- 
AGEPALETTE message. 

pPalette (PVOID)—input 

An array of RGB entries. 


MCI_PLAY_PARMS 

This structure contains the fields for the MCI_PLAY message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulFrom (ULONG)—input 

The position to play from. 

ulTo (ULONG)—input 

The position to play to. 


MCI_POSITION_PARMS 

This structure contains the fields for the MCI_SET_POSITION_ADVISE 
message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 
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ulUnits (ULONG)—input 

Specifies the position-change notification interval in the currently set time 
format for the device. 

usUserParm (USHORT)—input 

User parameter returned on position-change notification messages 

(MM_MCIPOSITIONCHANGE). 

usReservedO (USHORT)—input 
Reserved. 

usReservedl (ULONG)—input 
Reserved. 


MCI_RECORD_PARMS 

This structure contains the fields for the MCI_RECORD message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulFrom (ULONG)—input 

The media position at which recording is to begin. 

ulTo (ULONG)—input 

The media position at which recording is to end. 


MCI_RESTORE_PARMS 

This structure contains the fields for the MCI_RESTORE message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 
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SrcRect (RECTL)—input 

The source image rectangle of the area to restore. 

DestRect (RECTL)—input 

The destination window rectangle of the area to restore. 

MCI_SAVE_PARMS 

This structure contains the fields for the MCI_SAVE message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

pszFileName (PSZ)—input 

A pointer to a NULL terminated buffer that contains a file name. 

MC l_S E E K_PA RMS 

This structure contains the fields for the MCI_SEEK message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTo (ULONG)—input 

The media position that is the target of the seek operation. 
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MCI_SEQ_SET_PARMS 

This structure contains the fields for the MCI_SET message used with MIDI 
sequencer devices. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTimeFormat (ULONG)—input 

The time format to be used by the device. 

ulSpeedFormat (ULONG)—input 

The speed format to be used by the device. 

ulAudio (ULONG)—input 

Channel number for the following operations: 

• MCI_SET_AUDIO_LEFT 

• MCI_SET_AUDIO_RIGHT 

• MCI_SET_AUDIO_ALL 
ulLevel (ULONG)—input 

Audio volume level as a percentage of maximum. 
ulOver (ULONG)—input 

Delay time for vectored change, in milliseconds, 
ulltem (ULONG)—input 

Item field for set item flags for such items as file format, image pelformat, 
brightness, and so forth. 

ulValue (ULONG)—input 

Value associated with item flag that sets items such as image pelformat and 
image file format. The ulValue is interpreted as a FOURCC value. 

ulTempo (ULONG)—input 

Tempo. 
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ulPort (ULONG)—input 
Output port. 

ulSlave (ULONG)—input 
Unused. 

ulMaster (ULONG)—input 
Unused. 

ulOffset (ULONG)—input 
Data offset. 


MCI_SET_PARMS 

This structure contains the fields for the MCI_SET message for devices that 
do not have device-specific extensions. 

Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTimeFormat (ULONG)—input 

The time format to be used by the device. 

ulSpeedFormat (ULONG)—input 

The speed format to be used by the device. 

ulAudio (ULONG)—input 

Channel number for the following operations: 

• MCI_SET_AUDIO_LEFT 

• MCI_SET_AUDIO_RIGHT 

• MCI_SET_AUDIO_ALL 
ulLevel (ULONG)—input 

Audio volume level as a percentage of maximum. 
ulOver (ULONG)—input 

Delay time for vectored change, in milliseconds. 
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ulltem (ULONG)—input 

Item field for set item flags for such items as file format, image pelformat, 
brightness, and so forth. 

ulValue (ULONG)—input 

Value associated with item flag that sets items such as image pelformat and 
image file format. The ulValue is interpreted as a FOURCC value. 


MCI_STATUS_PARMS 

This structure contains the fields for the MCI_STATUS message. 


Fields 


hwndCallback (HWND) —input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulReturn (ULONG)—input 

Contains the status information upon return. High order word could be 
value or other message. The format of this value is defined by the high order 
word of the value returned by the mciSendCommand API. This value is 
used by the mciSendString API to determine how to convert the ulReturn 
value to string form. 

ulltem (ULONG)—input 

The status item to query. 

ul Value (ULONG)—input 

The status value to extend the status structure. 
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MC l_STE P_PARMS 

This structure contains the fields for the MCI_STEP message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulStep (ULONG)—input 

The increment for which the step is specified in the current time format. 


MC l_S YN C_0 F F S ET_PA RMS 

This structure contains the fields for the MCI_SET_SYNC_OFFSET 
message. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulOffset (ULONG)—input 

The device media-position offset in the currently specified time format. 


MCI_SYSINFO_ALIAS 

This structure contains the fields for the MCI_SYSINFO message for setting 
and querying an alias associated with a particular device. 


Fields 


szInstallName[MAX_DEVICE_NAME] (CHAR)—input 
Device installation name. 

szAliasName[MAX_ALIAS_NAME] (CHAR)—input 


Alias name. 
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MCI_SYSINFO_CONNECT 

This structure contains the fields for a device connector. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

usConnectType (USHORT)—input 

Connector type. 

szToInstallName[MAX_DEVICE_NAME] (CHAR)—input 
Install name to which this connector is connected. 
usToConnectlndex (USHORT)—input 

Connector index to which this connector is connected. 


MC l_S YSIN F 0_C O N PA RAMS 

This structure contains the fields for device connections. 

Fields 

szInstallName[MAX_DEVICE_NAME] (CHAR)—input 
Device install name. 
usNumConnectors (USHORT)—input 
Number of device connectors. 
ConnectorList[MAX_CONNECTORS] (CHAR)—input 
Pointer to array of device connectors. 
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MCI_SYSINFO_DEFAULTDEVICE 

This structure contains the fields for the MCIJ3YSINFO message for setting 
and querying a default associated with a particular device type used with 
amplified mixer devices. 

Fields 

szInstallName[MAX_DEVICE_NAME] (CHAR)—input 
Device install name. 
usDeviceType (USHORT)—input 
Device type number. 

MCI_SYSINFO_DEVPARAMS 

This structure contains the fields for the MCI_SYSINFO message for setting 
and querying device specific fields. 

Fields 


szInstallName[MAX__DEVICE_NAME] (CHAR)—input 
Device install name. 

szDevParams[MAX_DEV_PARAMS] (CHAR)—input 
Device-specific fields. 


MCI_SYSINFO_EXTENSION 

This structure contains the fields for the MCI_SYSINFO message for setting 
and querying file extensions associated with a particular device. 


Fields 


szInstallName[MAX_DEVICE_NAME] (CHAR)—input 


Device install name. 
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usNumExtensions (USHORT)—input 
Number of extensions. 

szExtension[MAX_EXTENSIONS] [MAX_EXTENSION_NAME] (CHAR) 
—input 

Extension name array. 


MCI_SYSINFO_LOGDEVICE 

This structure contains the fields for the MCI_SYSINFO message for setting 
and querying logical devices. 

Fields 

szInstallName[MAX_DEVTCE_NAME] (CHAR)—input 
Device install name. 
usDeviceType (USHORT)—input 
Device type number. 
usDeviceFlag (USHORT)—input 

Flag indicating whether device is controllable or not. The following styles 
can be used: 

MCI_SYSINFO_DEVICESETTINGS 

Indicates the MCD has custom device settings page. 

MCI_SYSINFO_DEV_CONTROLLABLE 

If a device is controllable, it usually accepts a PLAY command. 

MCI_S YSINFO_DE V_NONC ONTROLLABLE 

Examples of non-controllable devices are speakers, headphones, micro¬ 
phones, and amp-mixer devices. 

szVersionNumber[MAX_VERSION_NUMBER] (CHAR)—input 
INI file version number. 

szProductlnfo[MAX_PRODINFO] (CHAR)—input 
Textual product description. 

szMCDDriver[MAX_DEVICE_NAME] (CHAR)—input 


MCI Driver dll name. 
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szVSDDriver[MAX_DEVICE_NAME] (CHAR)—input 
VSD dll name. 

szPDDName[MAX_DEVICE_NAME] (CHAR)—input 
Device PDD name. 

szMCDTable[MAX_DEVICE_NAME] (CHAR)—input 
Device type command table name. 
szVSDTable{MAX_DEVTCE_NAME] (CHAR)—input 
Device specific command table. 
usShareType (USHORT)—input 
Device sharing mode. 

szResourceName[MAX_DEVICE_NAME] (CHAR)—input 
Resource name. 

usResourceUnits (USHORT)—input 

Total resource units available for this device. 
usResourceClasses (USHORT)—input 
Number of resource classes for this device. 
ausClassArray[MAX_CLASSES] (USHORT)—input 
Maximum number of resource units for each class. 
ausValidClassArray [MAXCLASSES] [MAXCLASSES] (USHORT)—input 
Valid class combinations. A 1 in the matrix indicates a valid combination. 


MCI_SYSINFO_PARMS 

This structure contains the fields for the MCI_SYSINFO message. 

Fields 

hwndDummyCallback (HWND)—input 
Reserved. 

pszReturn (PSZ)—input 

A pointer to an application supplied buffer for the return string. 
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ulRetSize (ULONG)—input 

The size, in bytes, of the buffer for the return string. 
ulNumber (ULONG)—input 

A number indicating the device position in the Media Control Interface 
device table. 

usDeviceType (USHORT)—input 
The type of the device. 
usReservedO (USHORT)—input 
Reserved. 

ulltem (ULONG)—input 

Used to indicate the MCI_SYSINFO extended function to perform. 


MCI_SYSINFO_QUERY_NAME 

This structure contains the fields for the MCI_SYSINFO message for querying 
the names associated with a particular device. 

Fields 

szInstallName[MAX_DEVICE_NAME] (CHAR)—input 
Device install name. 

szLogicalName[MAX_DEVICE_NAME] (CHAR)—input 
Logical device name. 

szAliasName[MAX_ALIAS_NAME] (CHAR)—input 
Alias name. 

usDeviceType (USHORT)—input 
Device type number. 
usDeviceOrd (USHORT)—input 
Device type ordinal. 



546 Developing Multimedia Applications Under OS/2 


MCLSYSINFOJYPES 

This structure contains the fields for the MCI_SYSINFO message for setting 
and querying extended attributes associated with a particular device. 


Fields 


szInstallName[MAX_DEVICEJVAME] (CHAR)—input 
Device install name. 

szTypes[MAX_TYPEBUFFER+1 ] (CHAR)—input 

Extended type array. The attributes are separated by a comma and the list 
is NULL terminated. 


MC l_T OC_PARMS 

This structure contains the fields for the MCI_GETTOC message. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

pBuf (PTOCREC)—input 

Pointer to array of TOC records. 

ulBufSize (ULONG)—input 

Size of TOC records array. 


MCI_TOC_REC 

This structure contains the fields that make up the TOC record. 

Fields 

TrackNum (BYTE)—input 
Returned track number. 
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ulStartAddr (ULONG)—input 

Starting address of the track in MMTIME format. 
ulEndAddr (ULONG)—input 

Ending address of the track in MMTIME format 
Control (BYTE)—input 
Track control information. 
usCountry (USHORT)—input 
Country. 

ulOwner (ULONG)—input 
Owner. 

ulSerialNum (ULONG)—input 
Serial number. 


MCI_VD_PLAY_PARMS 

This structure contains the fields for the MCIJPLAY message for videodisc 
devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulFrom (ULONG)—input 

The position to play from. 

ulTo (ULONG)—input 

The position to play to. 

ulFactor (ULONG)—input 

The speed factor for playing in the current speed format. 
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MC l_VD_S ET_PARMS 

This structure contains the fields for the MCI_SET message for videodisc 
devices. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTimeFormat (ULONG)—input 

The time format to be used by the device. 

ulSpeedFormat (ULONG)—input 

The speed format to be used by the device. 

ulAudio (ULONG)—input 

Channel number for the following operations: 

• MCI_SET_AUDIO_LEFT 

• MCI_SET_AUDIO_RIGHT 

• MCI_SET_AUDIO_ALL 
ulLevel (ULONG)—input 

Audio volume level as a percentage of maximum. 
ulOver (ULONG)—input 

Delay time for vectored change, in milliseconds, 
ulltem (ULONG)—input 

Item field for set item flags for such items as file format, image pelformat, 
brightness, and so forth. 

ulValue (ULONG)—input 

Value associated with item flag that sets items such as image pelformat and 
image file format. The ulValue is interpreted as a FOURCC value. 

ulChannel (ULONG)—input 

The videodisc channel. 
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MCI_VID_OPEN_PARMS 

This structure contains the fields for the MCI_OPEN message for digital video 
devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCIJNOTIFY flag is specified. 

usDevicelD (USHORT)—input 

The device ID returned to the user. 

usReservedO (USHORT)—input 

Reserved field. 

pszDeviceType (PSZ)—input 
The type of the device. 
pszElementName (PSZ)—input 
The media element or NULL. 
pszAlias (PSZ)—input 
An optional device alias. 
hwndParent (HWND)—input 

The handle to use as the window parent. 
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MCI_VID_RECT_PARMS 

This structure contains the fields for the MCI_PUT and MCI_WHERE 
messages for digital video devices. 


Fields 


hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

rc (RECTL)—input 

Specifies or returns a rectangle array specifying the offset and size of a rec¬ 
tangle depending on the MCI command. 


MC LVI D_WI N DO W_PARMS 

This structure contains the fields for the MCI_WINDOW message used with 
digital video devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

hwndDest (HWND)—input 

A handle to the client window used for the destination of the digital video. 
usCmdShow (USHORT)—input 

Specifies how the window is displayed. 
usReservedl (USHORT)—input 
Reserved. 

pszText (PSZ)—input 

The text to use as the window caption. 
pszAlias (PSZ)—input 

The window alias for the display window. 
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MCI_WAVE_GETDEVCAPS_PARMS 

This structure contains the fields for the MCI_GETDEVCAPS message for 
waveform audio devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCIJVOTIFY flag is specified. 

ulReturn (ULONG)—input 

The format of the ulReturn value in this structure is defined by the high 
order word of the value returned by the mciSendCommand API. This 
value is used by the mciSendString API to determine how to convert the 
ulReturn value to string form. See the MCIDRV.H header file for a list of 
possible format values. 

ulltem (ULONG)—input 

A ULONG identifying an item field for GETDEVCAPS item to query. 
usMessage (USHORT)—input 

The message ID being queried if MCI_GETDEVCAPS is specified. 
usReservedO (USHORT)—input 
Reserved. 

ulLength (ULONG)—input 
Structure length in ULONGs. 
ulBitsPerSample (ULONG)—input 

Number of bits per sample in a waveaudio sample. Typically 8 or 16. 
ulFormatTag (ULONG)—input 
Format tag. 

ulSamplesPerSec (ULONG)—input 

Samples per second rate of waveform audio. 
ulChannels (ULONG)—input 

Number of channels. Typically 1 or 2. 
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ulFormatMode (ULONG)—input 

The format mode, either MCI_PLAY or MCI_RECORD. 


MCI_WAVE_SET_PARMS 

This structure contains the fields for the MCI_SET message for waveform 
audio devices. 

Fields 

hwndCallback (HWND)—input 

A window handle used for returning asynchronous notification messages. 
This parameter must be specified if the MCI_NOTIFY flag is specified. 

ulTimeFormat (ULONG)—input 

The time format to be used by the device. 

ulSpeedFormat (ULONG)—input 

The speed format to be used by the device. 

ulAudio (ULONG)—input 

Channel number for the following operations: 

• MCI_SET_AUDIO_LEFT 

• MCI_SET_AUDIO_RIGHT 

• MCI_SET_AUDIO_ALL 
ulLevel (ULONG)—input 

Audio volume level as a percentage of maximum. 
ulOver (ULONG)—input 

Delay time for vectored change, in milliseconds, 
ulltem (ULONG)—input 

Item field for set item flags for such items as file format, image pelformat, 
brightness, and so forth. 

ulValue (ULONG)—input 

Value associated with item flag that sets items such as image pelformat and 
image file format. The ulValue is interpreted as a FOURCC value. 
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uslnput (USHORT)—input 
The channel used for input. 
usReservedO (USHORT)—input 
Reserved. 

usOutput (USHORT)—input 
The channel used for output. 
usReservedl (USHORT)—input 
Reserved. 

usFormatTag (USHORT)—input 

Specifies the interpretation of the waveform data. 
usReserved2 (USHORT)—input 
Reserved. 

usChannels (USHORT)—input 
Specifies mono (1) or stereo (2). 
usReserved3 (USHORT)—input 
Reserved. 

ulSamplesPerSec (ULONG)—input 

The samples per second used for waveform. 
ulAvgBytesPerSec (ULONG)—input 
The average data rate in bytes per second. 
usBlockAlign (USHORT)—input 
The block alignment of the data. 
usReserved4 (USHORT)—input 
Reserved. 

usBitsPerSample (USHORT)—input 
The number of bits per sample. 
usReserved5 (USHORT)—input 


Reserved. 
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Multimedia Input/Output 


APIs 


mmioAdvance 


mmioAdvance 

Fills and empties the contents of an I/O buffer of a file set up for direct I/O 
buffer access. 


#define INCL_MMI00S2 
#include <os2me.h> 

USHORT mmioAdvance( HMMIO hmmio, 

PMMIOINFO pmmioinfo, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pmmioinfo (PMMIOINFO)—input 

A pointer to the MMIOINFO data structure that was filled in by 

mmioGetlnfo. 


555 
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usFlags (USHORT)—input 

Specifies options for the operation. Contains one or more of the following 
flags: 

MMIO_READ 

The buffer is refilled from the file. This flag is used when the caller has 
finished reading data from the I/O buffer and wants the buffer to be 
refilled (if possible). 

MMIOJVVRITE 

The buffer is written to the file and not refilled from the file. This flag is 
used when the caller has written to the end of the buffer and needs the 
buffer to be emptied (or expanded, in the case of a memory file). 

Return Values 

rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO.SUCCESS MMIOERR_WRITE_F AILED 

MMIOERRJJNBUFFERED MMIOERR_READ_F AILED 

MMIOERRJNVALID_HANDLE MMIOERR_SEEK_F AILED 

MMIOERR_INVALID_PARAMETER MMIOERR_NO_FLUSH_NEEDED 

MMIOERR_READ_ONLY_FILE MMIOERR_OUTOFMEMORY 

MMIOERR_WRITE_ONLY_FILE MMIOERR_CANNOTEXPAND 

MMIOERR_FREE_FAILED 

Remarks 

The mmioAdvance API does not change the current file position of the file 
represented by the hmmio parameter, that is, the pchNext field of the 
MMIOINFO structure passed in the pmmioinfo parameter will correspond to 
the same data position before and after mmioAdvance is called, hence pointing 
to the same piece of data that is now located at the beginning of the buffer. 
mmioAdvance simply makes available as much buffer space as possible for 
doing direct buffer reading or writing. 

When mmioAdvance returns from a call where the MMIO_READ flag was 
specified, there will be at least n bytes of data available to be read in the I/O 
buffer (that is, n bytes between pchNext and pchEndRead ), where n is the less¬ 
er of the I/O buffer size and the number of remaining bytes of data. When 
mmioAdvance returns from a call where the MMIO_WRITE flag was speci¬ 
fied, at least n bytes of free space in the I/O buffer (that is, n bytes between 
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pchNext and pchEndWrite), where n is specified in the aullnfo[0] field of the 
MMIOINFO structure passed on an mmioOpen called if the file is a memory 
file, or the size of the I/O buffer if the file is not a memory file. 

If the file is opened for reading, the I/O buffer is filled from the disk. If the file 
is opened for writing and the MMIO_DIRTY flag is set in the ulFlags field of 
the MMIOINFO structure, the buffer is written to disk. The pchNext , 
pchEndRead , and pchEndWrite fields of the MMIOINFO structure are updat¬ 
ed to reflect the new state of the I/O buffer. 

If the file was opened for both reading and writing, and the I/O buffer was 
written to, the contents of the I/O buffer are written to disk before the next 
buffer is read. If you have written to the I/O buffer, you must set the 
MMIO_DIRTY flag of the ulFlags field of the MMIOINFO structure before 
calling mmioAdvance. Otherwise, the buffer will not be written to disk. 

The pchNext field must also be updated to reflect the data written in the I/O 
buffer. The I/O buffer will be written up to (but not including) the position indi¬ 
cated by the pchNext field of MMIOINFO. 
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mmioAscend 


mmioAscend 

Ascends out of a chunk in a RIFF file that was descended into by 
mmioDescend or created by mmioCreateChunk. 


//define INCL_MMI00S2 
//include <os2me.h> 

USHORT mmioAscend( HMMIO hmmio, 

PMMCKINFO pckinfo, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pkinfo (PMMCKINFO)—input 

A pointer to the MMCKINFO structure that was filled by mmioDescend or 
mmioCreateChunk. 

usFlags (USHORT)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO_SUCCESS MMIO_INVALID_HANDLE 

MMIO_INVALID_PARAMETER MMIOERR_CANNOT WRITE 
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Remarks 

If the chunk is descended into using mmioDescend, an mmioAscend seeks to 
the location following the end of the chunk (past the extra pad byte, if any). If 
the chunk was created and descended into using mmioCreateChunk, or if the 
MMIO_DIRTY flag in the ulFlags field of MMCKINFO structure passed on 
pckinfo parameter is set, then the current file position is assumed to mark the 
end of the data portion of the chunk. If the chunk size is not the same as the 
value that was stored in ckSize field of MMCKINFO before 
mmioCreateChunk or mmioDescend was called, then mmioAscend seeks 
back and corrects the chunk size in the chunk header before ascending from 
the chunk. Also, if the chunk size is odd, then mmioAscend writes a null pad 
byte at the end of the chunk. 
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mmioCFAddElement 


mmioCFAddElement 

Adds an element to the CGRP chunk of an open RIFF compound file. 


#define INCL_MMI00S2 
^include <os2me.h> 

ULONG mmioCFAddElement( HMMCF hmmcf, 

PSZ pszElementName, 
FOURCC fccType, 
PCHAR pchBuffer, 
LONG cchBytes, 

ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound file handle returned by mmioCFOpen. 
pszElementName (PSZ)—input 

A pointer to the name of the element that is to be added to the compound file 
resource group (CGRP). The symbols + and I are not valid with an element 
name. Element names follow the same naming conventions as those used for 
the DOS operating system. 

fccType (FOURCC)—input 

The four-character code (FOURCC) of the element. 

pchBuffer (PCHAR)—input 

A pointer to the caller-supplied buffer containing the element data. 
cchBytes (LONG)—input 

Length of caller-supplied buffer. 
ulFlags (ULONG)—input 

Specifies options for the operation. Contains 0 or the following flag: 

MMIO_CFJENTRYJEXISTS 

Set only if the compound-file table on contents (CTOC) entry for this ele¬ 
ment already exists. 
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Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS MMIOERR_READ_ONLY_FILE 

MMIOERR_INVALID_HANDLE MMIO_CF_FAILURE —A call to 

mmioGetLastError may return: 

MMIOERR_INVALID_PARAMETER MMIOERR.INTERNAL 

SYSTEM. 


Remarks 

The compound-file table of contents (CTOC) entry for the element does not 
have to exist prior to the call. mmioCFAddElement adds the entry if it does 
not exist. The mmioCFAddElement API writes the element to the end of the 
compound-file resource group (CGRP) chunk. The user’s buffer contains the 
element data. 

This API is used when the element exists but is not contained in the RIFF 
compound file. If the element does not exist, use mmioOpen with the 
MMIO_CREATE flag to add a newly created element to the RIFF compound 
file. In that case, the file name used with mmioOpen must contain the com¬ 
pound file and element name (that is, aaa.bnd+element). 

The user is not required to use mmioCFAddElement to add an element to a 
RIFF compound file. However, one would need to replicate the following API 
that mmioCFAddElement provides: 

• Seek to the start of the RIFF compound file. 

• Descend to the BND chunk. 

• Descend to the CGRP chunk. 

• Seek to the end of the CGRP. 

• mmioWrite to write all of the data. 

• Ascend the CGRP to correct the size. 

• Ascend the BND to correct the size. 

• If the CTOC already exists, call mmioCFChangeEntry to update the 
data offset and size of the element. 

• If not, call mmioCFAddEntry to add the CTOC entry. 
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mmioCFAddEntry 

mmioCFAddEntry 

Adds an entry to the CTOC chunk of an open RIFF compound file. 

#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFAddEntry( HMMCF hmmcf, 

PMMCTOCENTRY pmmctocentry, 

ULONG ulFIags ) 

Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 

pmmctocentry (PMMCTOCENTRY)—input 

A pointer to a user-supplied CTOC structure containing the CTOC data. 
This structure is variable in size, and the user must ensure enough memory 
has been allocated for it. 

ulFlags (ULONG)—input 

Reserved for future use, and must be set to zero. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR_INVALID_HANDLE MMIO_READ_ONLY_FILE 

MMIO_CF_FAILURE —A call to 
mmioGetLastError may 
return one of the following errors: 

MMIOERR_CF_DUPLICATE_SEEN, 

MMIOERR_NO_CORE, or 
MMIOERR_INTERNAL_SYSTEM. 
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Remarks 

The identifier for the entry is the element name, which is appended to the end 
of the MMCTOCENTRY structure passed in the pmmctocentry parameter. It 
is not case-sensitive. If mmioCFAddEntry expands the current number of 
entries past the number currently allocated, when a mmioCFClose is called, 
the CTOC gets written following the CGRP chunk in the file. The 
mmioCFAddEntry API operates only on the CTOC in memory and does not 
do any expansion of the file itself. 



564 Developing Multimedia Applications Under OS/2 


mmioCFChangeEntry 


mmioCFChangeEntry 

Changes a CTOC entry in an open RIFF compound file. 


#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFChangeEntry( HMMCF hmmcf, 

PMMCTOCENTRY pmmctocentry, 
ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 

pmmctocentry (PMMCTOCENTRY)—input 

A pointer to the MMCTOCENTRY structure containing the modified CTOC 
data. This structure is variable in size and the user must ensure enough 
memory has been allocated for it. 

ulFlags (ULONG)—input 

Specifies options for the operation. It contains none or the following flag: 

MMIO.CHANGEDELETED 

This flags specifies a deleted CTOC entry is to be changed. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_CF_SUCCESS 

MMIOERR_INVALID_HANDLE 

MMIOERR_INVALID_PARAMETER 

MMIOERR_READ_ONLY_FILE 

MMIO_CF_FAILURE—A call to mmioGetLastError may return one of the 
following errors: MMIOERR_CF_ENTRY_NOT_FOUND or MMIOERR. 
INTERNAL. SYSTEM. 
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Remarks 

The identifier for the entry is the element name, which is appended to the end 
of the MMCTOCENTRY structure passed in the pmmctocentry parameter. 
(The element name itself cannot be modified.) mmioCFChangeEntry updates 
the compound-file CTOC entry with the information contained in the pmmcto¬ 
centry parameter MMCTOCENTRY structure. If the compression technique 
specified in the ulCompressTech field of MMCTOCENTRY structure is 
changed, the ulUncompressBytes field of the MMCTOCENTRY structure 
must also be changed. When the compression technique is NULL, the 
ulUncompressBytes field must be the size in bytes of the element when it is 
uncompressed. Consider calling mmioCFFindEntry to fill in the MMCTO¬ 
CENTRY structure prior to calling this information. 
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mmioCFClose 


mmioCFClose 

Closes a RIFF compound file that was opened by mmioCFOpen. 

#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFClose( HMMCF hmmcf, 

ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 
ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

mmio_read_only_filemmio_cf_success 

mmio_read_only_filemmioerr_invalid_handle 

MMIO_READ_ONLY_FILEMMIO_CF_FAILURE—A call to mmioGetLast- 
Error may return one of the following errors: MMIOERR_CF_NON_BND_FILE, 
MMIOERR_CF_ELEMENT$_OPEN, or MMIOERR_INTERNAL_SYSTEM. 


Remarks 

This API decrements the usage count of the compound-file table of contents 
(CTOC) maintained in memory for this RIFF compound-file. If the usage count 
drops to 0, the CTOC is written to disk, and the RIFF compound-file handle is 
closed. An mmioCFClose operation fails if this RIFF compound-file has any 
open elements. The user will get an error if mmioClose is used instead of 
mmioCFClose when trying to close a RIFF compound-file. 
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If this is an ExitList close, all open elements are closed, and the mmioCFClose 
operation is allowed. If the compound-file was opened as read-only, the CTOC 
will not be rewritten. 

If the mmioCFClose API fails and the user had modified compound-file- 
resource-group (CGRP) elements, the data stored on the file is inconsistent. To 
correct the problem, the user must create free file space and attempt to close 
again. 
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mmioCFCompact 


mmioCFCompact 

Compacts the elements of a RIFF compound file. 

#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFCompact( PSZ pszFileName, 

ULONG ulFlags ) 


Parameters 

pszFileName (PSZ)—input 

The name of the RIFF compound file to compact. 
ulFlags (ULONG)—input 

This parameter is intended for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

MMIO.SUCCESS MMIOERR_INVALID_FILENAME 

MMIO_ERROR MMIOERR_INTERNAL_SYSTEM 

MMIOERR_NO_CORE 

Remarks 

This API is useful for writers of audio-enabling macros who use compound files 
in their implementation. 

The mmioCFCompact API does not use a compression algorithm to compact 
the compound file. It merely deletes elements in the CGRP whose MMCTO- 
CENTRY ulMedType field is marked as FOURCC__DEL and updates the 
MMCTOCENTRY ulMedType field to FOURCC_FREE. At the completion of 
the API, CTOC entries are sorted according to offset. Entries might not remain 
sorted if subsequent appends are made. 

The mmioCFCompact API compacts the file in place; that is, the API 
rewrites the file within the same buffer as the source to save memory. No 



APPENDIX B: Multimedia Input/Output 569 

original can be salvaged if an error occurs during compaction. If this behavior 
is unacceptable, use the mmioCFCopy API. 

The mmioCFCopy API also compacts a file, but it rewrites the file to a speci¬ 
fied target name. The target name cannot be the same as the source file name. 
Therefore, with this API, the source file must be deleted. 
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mmioCFCopy 


mmioCFCopy 

Copies th CTOC and CGRP chunks from an open RIFF compound file to anoth¬ 
er RIFF compound file. 


#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFCopy( HMMCF hmmcfSource, 

PSZ pszDestFi1eName, 
ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. This is the source 
file to be copied. 

pszDestFileName (PSZ)—input 

The pointer to the name of the destination file. The RIFF compound-file is 
copied to the destination file. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

MMIO_CF_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR_INVALID_HANDLE MMIOERR_READ_ONLY_FILE 

MMIO_CF_FAILURE—A call to mmioGetLastError may return one of the 
following errors: MMIOERR_CF_ELEMENTS_OPEN, MMIOERR_NO_CORE, or 
MMIOERR_INTERNAL_S Y STEM. 
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Remarks 

mmioCFCopy copies the CTOC and CGRP chunks of an open source RIFF 
compound-file to the target file. Deleted elements are not copied to the new file. 
mmioCFCopy opens the target file (using mmioOpen with the MMIO_CRE- 
ATE flag) and builds a RIFF BND header at the beginning of the file. The 
CTOC and CGRP chunks then are copied. Notice that it is invalid to copy the 
RIFF compound-file to itself. Upon completion of the copy operation, the target 
file is closed and resides on the file system, while the source file is unaltered. 
The target file must not be opened before mmioCFCopy is called. 

As a note for performance considerations, the API either copies the entire 
CTOC and CGRP chunks in one single system buffer, or does a fixed page-size 
copy. The method used depends on the size of the RIFF compound-file and is 
determined by the system. If the copy operation fails, the target file is deleted. 

If the target already exists, it is overwritten by the copy operation. 
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mmioCFDeleteEntry 


mmioCFDeleteEntry 

Deletes a CTOC entry in an open RIFF compound file. 


#define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmioCFDeleteEntry( HMMCF hmmcf, 

PMMCTOCENTRY pmmctocentry, 
ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 

pmmctocentry (PMMCTOCENTRY)—input 

A pointer to the MMCTOCENTRY data structure containing the RIFF 
compound file element name. This structure is variable in size, and the user 
must ensure enough memory has been allocated for it. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

MMIO_CF_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERRJNVALIDJHANDLE MMIOERR_READ_ONLY_FILE 

MMIO_CF_FAILURE—A call to mmioGetLastError may return one of the 
following errors: MMIOERR_CF_ENTRY_NOT_FOUND or MMIOERR. 
INTERNAL_SYSTEM. 
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Remarks 

The identifier for the entry is the element name, which is appended to the end 
of the MMCTOCENTRY structure passed in the pmmctocentry parameter. 
The CTOC entry is marked as deleted by setting the MMCTOCENTRY 
ulMedType field to FOURCCJDEL. The actual element data remains in place. 
To remove data that was previously marked for deletion, use mmioCFCopy. 
The result will be a compressed file with all those elements marked for dele¬ 
tion physically removed. 
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mmioCFFindEntry 


mmioCFFindEntry 

Finds a CTOC entry in an open RIFF compound file. 


#define INCL_MMI00S2 
#iDelude <os2me.h> 

ULONG mmioCFFindEntry( HMMCF hmmcf, 

PMMCTOCENTRY pmmctocentry, 
ULONG ulFlags ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 

pmmctocentry (PMMCTOCENTRY)—input/output 

A pointer to the MMCTOCENTRY structure containing the name of the 
RIFF compound-file element to search for. This structure is variable in size 
and the user must ensure enough memory has been allocated for it. 

ulFlags (ULONG)—input 

This parameter can be used to specify that an element is to be searched for 
by some attribute other than name. The following flags are supported: 

MMIO_FINDFIRST —Find the first entry in the CTOC table. 

MMIO_FINDNEXT —Find the next entry in the CTOC table after the entry previ¬ 
ously found and returned in the pmmctocentry parameter. The pmmctocentry para¬ 
meter must contain the previous CTOC entry. 

MMIO_FINDDELETED —Find an entry in the CTOC table that has been marked 
as deleted. 

MMIO_FINDUNUSED —Find an entry in the CTOC table that is marked as 
unused. A default compound file contains 16 unused CTOC entries in the CTOC 
table. As each CTOC entry and element is added, one of these unused entries is used. 
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The MMIO_FINDFIRST and MMIO_FINDNEXT flags are mutually exclu¬ 
sive. An MMIOERR_CF_ENTRY_NOT_FOUND error is returned if a match¬ 
ing entry is not found or if the MMIO_FINDNEXT was specified and no more 
entries match the search CTOC entry. 

Return Values 

rc (ULONG)—return value 

MMIO_CF_SUCCESS MMIOERR_CF_ENTRY_NOT_FOUND 

MMIOERR_INVALID_HANDLE 

MMIOERR_INVALID_PARAMETER 

MMIOERR_READ_ONLY_FILE 

MMIO_CF_FAILURE—A call to mmioGetLastError may return one of the following 

errors: MMIOERR_WRITE_ONLY_FILE or MMIOERR_INTERNAL_SYSTEM. 

Remarks 

The search is not case-sensitive; the flags operate as follows: 

• MMIOJFTNDFXRST and MMIOJFINDNEXT cannot be specified 
together. 

If an element is specified, it is ignored; if no element is specified, the flags oper¬ 
ate as follows: 

• If MMIO_FINDFIRST is specified, the first non-deleted entry is 
returned. 

• If MMIO_FINDFIRST and MMIO.FINDDELETED are specified, the 
first deleted element is returned. 

All other cases use the element name in the search, and the flags operate as 
follows: 

• If no flags are specified, the first non-deleted entry that matches the ele¬ 
ment name passed in is returned. 

• If MMIO_FINDNEXT is specified, the entry that matches the element 
name passed in is found. The first non-deleted entry following this entry 
is returned. 

• If MMIO_FINDDELETED is specified, the entry that matches the ele¬ 
ment name passed in is found. If the entry is marked deleted, it is 
returned. 
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• If MMIO_FINDNEXT and MMIO.FINDDELETED are specified, the 
entry that matches the element name passed in is found. The element 
name passed in may refer to an existing or deleted entry. At this point, 
the next entry that is deleted is returned. 

If the API succeeds, the pmmctocentry parameter MMCTOCENTRY structure 
is filled in with information about the CTOC entry. The user can proceed 
through the CTOC entry list be using MMIOJFINDFIRST followed by a 
series of MMIO_FINDNEXT actions using the information from the previous 
call. 
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mmioCFGetlnfo 


mmioCFGetlnfo 

Retrieves the CTOC header of an open RIFF compound file. 


^define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioCFGetInfo( HMMCF hmmcf, 

PMMCFINFO pmmcfinfo, 
ULONG cBytes ) 


Parameters 

hmmcf (HMMCF)—input 

A RIFF compound-file handle returned by mmioCFOpen. 

pmmcfinfo (PMMCFINFO)—input/output 

A pointer to the MMCFINFO data structure, which is filled with the CTOC 
header. This structure is variable in size, and the user must ensure enough 
memory has been allocated for it. 

cBytes (ULONG)—input 

Size of the buffer to which the pmmcfinfo parameter points. This is the max¬ 
imum number of bytes that will be copied. 

Return Values 

rc (ULONG)—return value 

MMIOERR_INVALID_HANDLE MMIOERR_INTERNAL_SYSTEM 
MMIOERR_WRITE_ONLY_FILE 

Remarks 

The information copied to the pmmcfinfo parameter consists of a MMCFINFO 
structure followed by the variable-length arrays: aulExHdrFldUsage, 
aulExEntFldUsage , and aulExHdrField. 

To find out how large a buffer the user needs to allocate, call mmioCFGetlnfo 
with cBytes parameter equal to the size of a ULONG. This will return the first 
field of the CTOC header, which happens to be the size of the header. This size 
can be used in the cBytes parameter on a subsequent call. 
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mmioCFOpen 


mmioCFOpen 

Opens a RIFF compound file by name. 


#def ine INCL_MMI00S2 
^include <os2me.h> 

HMMCF mmioCFOpen( PSZ pszFileName, 

PMMCFINFO pmmcfinfo, 
PMMIOINFO pmmioinfo, 
ULONG ulFlags ) 


Parameters 

pszFileName (PSZ)—input 

The name of the RIFF compound-file to open, 
pmmcfinfo (PMMCFINFO)—input 

A pointer to the MMCFINFO data structure containing optional header 
information. It can be NULL. 

pmmioinfo (PMMIOINFO)—input 

A pointer to the MMIOINFO information structure containing optional 
open information that is passed to mmioOpen. It can be NULL. 

ulFlags (ULONG)—input 

Contains none or some of the following flags. The MMIO_READ, 
MMIOJWRITE, and MMIO_RE AD WRITE flags are mutually exclusive. 

MMIO_READ —Opens the file for reading only. This is the default if 

MMIO_WRITE and MMIO_READWRITE are not specified. 

MMIO_WRITE —Opens the file for writing. A file cannot be read from if the 
file is opened in this mode. 

MMIO_READWRITE —Opens the file for both reading and writing. 

MMIO_EXCLUSIVE —Opens the file with exclusive mode, denying other 
processes both read and write access to the file. mmioOpen fails if the file 
has been opened in any other mode for read or write access, even by the cur¬ 
rent process. 
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MMIO_DENYWRITE —Opens the file and denies other processes write 
access to the file. mmioCFOpen fails if the file has been opened by a com¬ 
patible process or for write access by any other process. 

MMIO_DENYREAD —Opens the file and denies other processes read 
access to the file. mmioCFOpen fails if the file has been opened by a com¬ 
patible process or for read access by any other process. 

MMIO_DENYNONE —Opens the file and denies other processes read 
access to the file. mmioCFOpen fails if the file has been opened by a com¬ 
patible process or for read access by any other process. 

MMIO_CREATE —Directs mmioCFOpen to create a new file. If the file 
already exists, it is truncated to 0 length, unless it is already opened. In that 
case, a HMMCF to the RIFF compound-file is returned. 

Return Values 

rc (HMMCF)—return value 

If the API succeeds, the handle to the RIFF compound-file is returned. A 
NULL is returned if it fails. 


Remarks 

This API will either construct a compound-file table of contents (CTOC) in 
memory for this compound-file or give the caller access to a CTOC that already 
exists in memory for this compound-file. Only one CTOC for a particular com¬ 
pound-file is maintained in memory at any given time. This CTOC is shared by 
any process that needs access to the file. 

This API will determine whether the CTOC for this compound-file is being 
maintained in memory. If so, the access and sharing modes are checked to 
ensure that an open operation is allowed. The existing HMMCF for the CTOC 
is returned to the caller. If the file had not been previously opened, this API 
will construct a CTOC in memory for this file. If the name is not pointing to a 
valid BND file, an error is returned. 

The RIFF compound-file name cannot contain + or I because they are used to 
express elements of compound-files. 

The access and sharing flags are maintained only within the set of compound- 
file APIs. If the RIFF compound-file or elements are accessed without using 
the compound-file calls, the access and sharing modes are unpredictable. An 
mmioOpen operation with a fully qualified element name is considered a com¬ 
pound-file call, because it internally calls mmioCFOpen ; thus the flags are 
predictable in that case. 
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Access and sharing modes are supported for compound-files. However, these 
modes are enforced only within the MMIO services compound-file APIs and the 
mmioOpen of compound-file elements. The sharing modes work as in the base 
operating system except that elements ignore the sharing mode of the RIFF 
compound-file. Elements do obey the access modes of the RIFF compound-file. 

Elements can be opened and used from the compound-file by sending the ele¬ 
ment name that is store in the CTOC to the mmioOpen API. 

The FOURCC of FOURCC_BND should be used only for the element and not 
the compound-file itself. That is, do not specify FOURCC_BND in the 
MMIOINFO fccIOProc field when using mmioCFOpen. 
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mmioCFSetlnfo 


mmioCFSetlnfo 

Modifies information that is stored in the CTOC header of an open RIFF com¬ 
pound file. 


//define INCL_MMI00S2 
#iinclude <os2me.h> 

ULONG mmioCFSetInfo( HMMCF hmmcf, 

PMMCFINFO pmmcfinfo, 
ULONG cBytes ) 


Parameters 

hmmcf (HMMCF)—input 

A pointer to a user-supplied buffer that contains the modified CTOC header. 
A RIFF compound-file handle is returned by mmioCFOpen. 

pmmcfinfo (PMMCFINFO)—input 

A pointer to the MMCFINFO data structure that contains the modified 
CTOC header. This buffer was filled in by mmioCFGetlnfo and then modi¬ 
fied by the user. 

cBytes (ULONG)—input 

Size of the buffer that the pmmcfinfo parameter points to. This is the maxi¬ 
mum number of bytes that will be copied. 

Return Values 

rc (ULONG)—return value 

These return codes indicate success or type of failure. If the API succeeds, 
the number of bytes copied is returned. NULL is returned for a failure. A 
call to mmioGetLastError may return one of the following errors: MMIO- 
ERR_INVALID_PARAMETER, MMIOERR_RE AD_ONLY JFILE , or 
MMIOERR_INTERNAL_SYSTEM. 
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Remarks 


The only data that should be modified by the user is the aulExHdrFldUsage 
and aulExHdrField fields appended to the end of the MMCFINFO structure 
passed on the pmmcfinfo parameter. 
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mmioClose 


mmioClose 

Closes a file opened by mmioOpen. 

#def ine INCL_MMI00S2 
#include <os2me.h> 

USHORT mmioCloseC HMMIO hmmio, 

USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen . 
usFlags (USHRT)—input 

Contains nothing or the following flag: 

MMIO_FHOPEN —This flag is used to tell the I/O procedure to not close 
the file for files of type FOURCC_DOS. This allows an HMMIO instance to 
be closed in cases where a DOS file handle was provided to the I/O proce¬ 
dure on an mmioOpen call. 


Return Values 


rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO.SUCCESS MMIOERR_INVALID_HANDLE 

MMIOERR.CANNOTWRITE MMIOERR_WRITE_F AILED 

MMIO.WARNING 


Remarks 


A buffer is automatically emptied when a file is closed by calling mmioClose. 
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mmioCreateChunk 


mmioCreateChunk 

Creates a chunk in a RIFF file that was opened by mmioOpen. 


#define INCL_MMI00S2 
#include <os2me.h> 

USHORT mmioCreateChunk( HMMIO hmmio, 

PMMCKINFO pckinfo, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen . 

pckinfo (PMMCKINFO)—input/output. 

A pointer to MMCKINFO data structure that is to be filled in as follows: 

ckid —Must be the chunk ID of the chunk to create. If the usFlags parameter 
includes MMIO_CREATERIFF or MMIO.CREATELIST, this field will 
be filled on return from this API. 

ckSize —Must be the size of the data portion of the chunk, including the form 
type or list type (if any) but not including the 8-byte chunk header or the 
terminating null (if any). If this value is not correct when mmioAscend is 
called to mark the end of the chunk, then mmioAscend will seek back and 
correct the chunk size. 

fccType —Must contain the form type or list type, respectively, is usFlags 
parameter contains MMIO_CREATERIFF or MMIO_CREATELIST. 

ulDataOffset —This field will be filled in on return from this API. It will con¬ 
tain the file offset of the beginning of the data portion of the chunk. 

ulFlags —This field will be filled in on return from this API. It will contain 
the MMIO_DIRTY flag to indicate this chunk was created with an 

mmioCreateChunk call. 
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usFlags (USHORT)—input 

Contains none or one of the following flags: 

MMIO_CREATERIFF —Create a chunk with an ID ( ckid field) of RIFF and 
a form type in the fccType field. 

MMIO_CREATELIST —Create a chunk with an ID {ckid field) of LIST and 
list type in the fccType field. 

Return Values 

rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR_INVALID_HANDLE MMIOERR_CANNOTWRITE 


Remarks 

mmioCreateChunk creates a new chunk; that is, it writes a chunk header 
starting at the current file position, and descends into the chunk. The chunk 
ID is copied from the ckid field of the provided MMCKINFO structure. Call 
mmioAscend after the chunk data has been written. The ckSize field is 
assumed to be a proposed chunk size. If it turns out to be correct; that is, if you 
write that much data into the chunk before calling mmioAscend to end the 
chunk, mmioAscend will not have to seek back and correct the chunk header. 
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mmioDescend 


mmioDescend 

Descends into a RIFF file chunk beginning at the current file position, or 
searches for a specified chunk. 


#define INCL_MMI00S2 
#include <os2me.h> 

USHORT mmioDescencK HMMIO hmmio, 

PMMCKINFO pckinfo, 
PMMCKINFO pckinfoParent, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pckinfo (PMMCKINFO)—input 

A pointer to the caller-supplied MMCKINFO structure that is to be filled in 
as follows: 

ckid —Set to the chunk ID of the chunk. 

ckSize —Set to the size of the data portion of the chunk, including the form 
type or list type (if any) but not including the 8-byte chunk header or the 
terminating null (which is present only if chunk size is odd). 

fccType —The field contains the form type for RIFF chunks, the list type for 
LIST types, or a NULL value. 

ulDataOffset —The file offset of the beginning of the data portion of the 
chunk, which begins after the 8-byte chunk header. If the chunk is a LIST 
chunk or a RIFF chunk, then this field must contain the the offset of the list 
type or form type. 

ulFlags —Contains other information about the chunk. Currently, 
mmioDescend zeros this field. 
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pckinfoParent (PMMCKINFO)—input 

Specifies a pointer to the MMCKINFO data structure, which is an optional 
caller-supplied structure that refers to the parent of the chunk that is being 
searched for. 

A parent of a chunk is the enclosing chunk—only RIFF and LIST chunks 
can be parents. If this field is non-NULL, it is assumed that it was filled or 
return from an mmioDescend call to descend into the parent chunk, and 
mmioDescend will only search for and descend into a chunk within the par¬ 
ent chunk. If this parameter is NULL, this restriction is not imposed. 
mmioDescend checks only if a chunk is past the end of a given parent 
chunk, not before the beginning of the parent chunk. Also, mmioDescend 
checks only if the beginning of a chunk is past the end of the parent chunk. 

usFlags (USHORT)—input 

Contains 0 or one of the following flags: If none of these flags are specified, 
mmioDescend descends into the chunk that starts at the current file posi¬ 
tion. 

MMIO_FINDCHUNK —Search for a chunk with a specific ID. The ckid 
field of MMCKINFO passed in on the pckinfo parameter should contain the 
ID of the chunk to search for when mmioDescend is called. 

MMIO.FINDRIFF— Search for a chunk with an ID of FOURCCJRIFF 
and with a specific form type. The fccType field of MMCKINFO passed in on 
the pckinfo parameter contains the form type of the RIFF chunk to search 
for when mmioDescend is called. 

MMIO_FINDLIST —Search for a chunk with an ID of FOURCC.LIST and 
with a specific list type. The fccType field of MMCKINFO passed in on the 
pckinfo contains the list type of the LIST chunk to search for when 
mmioDescend is called. 

Return Values 

rc (USHORT)—return value 

MMIO.SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR_INVALID_HANDLE MMIOERR.CHUNKNOTFOUND 

Remarks 


A RIFF chunk consists of a four-byte chunk ID ckid (type FOURCC), followed 
by a four-byte chunk size , ckSize (type ULONG), followed by the data portion 
of the chunk, followed by a 0 pad byte if ckSize is odd. If ckid is 
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FOURCC_RIFF or FOURCC_LIST, then the first four bytes of the data por¬ 
tion of the chunk are either a form type or list type. ckSize is the size of the 
chunk data, not including ckid or ckSize or the pad byte (if any), but including 
the form type or list type (if present). 

When mmioDescend is called, it assumes that the current file position is the 
beginning of a chunk header. If pckinfoParent is given, mmioDescend 
assumes that the current file position is within pckinfoParent (a RIFF or LIST 
chunk). If mmioDescend succeeds, the current file position will either be just 
after the form type or list type (12 bytes from the beginning of the chunk ID) if 
the chunk ID is FOURCC_RIFF or FOURCCJLIST, or at the start of the 
data portion of the chunk (8-bytes from the beginning of the chunk ID). 

For efficiency of RIFF I/O, it is recommended that hmmio parameter be set up 
for buffered I/O. Note that the constants, FOURCC_RIFF and 
FOURCCJLIST, are defined to be the four-character codes, RIFF and LIST, 
respectively. 
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mmioDetermineSSIOProc 


mmioDetermineSSIOProc 

Determines the storage system of the media data object. 


#def ine INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioDetermineSSIOProc( PSZ pszFileName, 

PMMIOINFO pmmioinfo, 
PFOURCC pfccStorageSystem, 
PSZ pszParsedRemainder ) 


Parameters 

pszFileName (PSZ)—input 

The file name of the media object. This parameter can be NULL, 
pmmioinfo (PMMIOINFO)—input 

A pointer to a MMIOINFO data structure that might contain additional 
data. Normally this is NULL, but it is needed for compound-file elements 
that are not completely valid. 

pfccStorageSystem (PFOURCC)—input/output 

Pointer to the FOURCC of the storage system that is returned when suc¬ 
cessfully completed. 

pszParsedRemainder (PSZ)—input/output 

Pointer to the parsed file name that is returned when successfully completed. 

Return Values 

rc (ULONG)—return value 

MMIO_SUCCESS MMIO.ERROR 

MMIOERR_INVALID_PARAMETER 
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Remarks 

mmioDetermineSSIOProc processes the MMIOINFO data first to check for 
a storage system I/O procedure specified in the fccChildlOProc field. If it is not 
NULL, the fccChildlOProc is returned as the storage system FOURCC. 
Otherwise, the file name is parsed for a separator character; if one is found, 
the extension is converted to the storage system FOURCC. In this case, 
mmioDetermineSSIOProc returns the parsed string that consists of those 
characters following the separator character. The name is parsed from left to 
right. 
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mmioFindElement 


mmioFindElement 

A 16-bit API to enumerates the entries of a compound file. 


#define INCL_16 
#define INCL_MACHDR 
^include <os2me.h> 

ULONG mmioFindElement ( ULONG ulCode, 

PSZ pszElement, 
ULONG ulElementLen, 
PSZ pszFile, 

ULONG ulReserved ) 


Parameters 

ulCode (ULONG)—input 

The following flags are used to control the find operation: 

MMIO_FE_FINDFIRST —Finds the first element in the specified com¬ 
pound file. 

MMIO_FE_FINDNEXT —Finds the next element in the specified com¬ 
pound file. 

MMIO_FE_FINDELEMENT —Searches for an element in the specified 
compound file. 

MMIO_FE_FINDEND —Completes the search of a compound file. 
pszElement (PSZ)—input/output 

A pointer to a compound file element name. 
ulElementLen (ULONG)—input 

Length of the buffer to which the pszElement parameter points. 
pszFile (PSZ)—input 

A pointer to a RIFF compound file name. This parameter should contain just 
the name of the compound file and not include the element name specification. 
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ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR__CF_ENTRY_N OT_FOUND ERROR_INVALID_PARAMETER 

ERROR_BUFFER_OVERFLOW 

Remarks 

The mmioFindElement API is a high-level interface to enumerate elements 
from a compound file. 

For MMIO_FE_FINDFIRST and MMIO_FE_FINDNEXT, the pszElement 
parameter contains the name of an element in the specified compound file 
upon return. Only one MMIO_FE_FINDFIRST and MMIO_FE_FINDNEXT 
sequence is supported for a file at any one time. If an element is not found, 
MMIOERR__CF_ENTRY_NOT_FOUND is returned and the pszElement 
parameter is set to an empty string. 

For MMIO_FE_FINDELEMENT, the element name specified in pszElement 
is searched for. If the name is found, a zero return code is returned. If the ele¬ 
ment is not found, then MMIOERR_CF_ENTRY_NOT_FOUND is returned, 
and the pszElement parameter is set to an empty string. 

MMIO_FE_FINDEND should be called after the search is complete. This flag 
indicates that the compound file should be closed. MMIO_FE__FINDFIRST 
opens the compound file on the first invocation, and the file remains open until 
MMIO_FE_FINDEND is called. The MMIO_FE_FINDEND flag must be 
sent after completing the search in order to close the file. 
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mmioFlirsh 


mmioFlush 

Forces the contents of an I/O buffer to be written to disk. 

//define INCL_MMI00S2 
//include <os2me.h> 

USHORT mmioFlush( HMMIO hmmio, 

USHORT usFlags ) 


Parameters 


hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
usFlags (USHORT)—input 

Contains one or more of the following flags: 

MMIO_EMPTYBUF —Empties the I/O buffer. The pchNext field of the 
MMIOINFO structure will point to pchEndRead. 

Return Values 


rc (USHORT)—return value 


MMIO.SUCCESS MMIOERR_WRITE_F AILED 

MMIOERR.INVALIDJIANDLE MMIOERR_NO_BUFFER_ALLOCATED 

MMIOERR_CANNOTWRITE MMIOERR_NO_FLUSH_NEEDED 

MMIOERR NO FLUSH FOR MEM FILE 


Remarks 


If the hmmio parameter represents a file that was opened using mmioOpen , 
and the hmmio parameter is currently set up for buffered I/O, and the buffer 
has been written into (by mmioWrite , or by direct caller access to the buffer 
using mmioGetlnfo) since the last time the buffer was flushed to disk, 
mmioFlush writes the buffer to the disk. 

If the hmmio parameter is a memory file or is unbuffered, this API returns the 
appropriate error message indicated. Note that mmioFlush might fail if there 
is insufficient disk space to write the buffer, even if the preceding mmioWrite 
APIs succeeded. 
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mmioFOURCC 


mmioFOURCC 

A macro to converts four characters to a four-character code (FOURCC). 


#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioF0URCC( CHAR chO, 
CHAR chi, 
CHAR ch2, 
CHAR ch3 ) 


Parameters 

chO (CHAR)—input 

The first character of the FOURCC code to be converted, 
chi (CHAR)—input 

The second character of the FOURCC code to be converted. 
ch2 (CHAR)—input 

The third character of the FOURCC code to be converted. 
ch3 (CHAR)—input 

The fourth character of the FOURCC code to be converted. 

Return Values 

rc (FOURCC)—return value 

The FOURCC converted from the four characters. 

Remarks 

This macro does not check to see if the four-character code follows any conven¬ 
tions regarding which characters to include in a FOURCC. The string is sim¬ 
ply copied to a FOURCC and padded with blanks to the right, if required, or 
truncated to four characters, if required. 
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mmioGetFormatName 


mmioGetFormatName 

Provides the descriptive name of the format supported by the I/O procedure. 


//define INCL_MMI00S2 
#i include <os2me.h> 

ULONG mmioGetFormatName( PMMFORMATINFO pmmformatinfo, 

PSZ pszFormatName, 

PLONG piBytesRead, 

ULONG ulReserved, 

ULONG ulFlags ) 


Parameters 

pmmformatinfo (PMMFORMATINFO)—input 

Pointer to an MMFORMATINFO structure that contains the fccIOProc 
field (FOURCC code of the I/O Procedure) and INameLength field (the 
length in bytes of the format name pointed to by the pszFormatName para¬ 
meter). 

pszFormatName (PSZ)—input/output 

Pointer to a format name. This API fills in the format name associated with 
the specified I/O Procedure, up to the length, in bytes, specified by 
INameLength field above. Make sure the buffer is INameLength +1 in length 
to handle the string terminator character. 

plBytesRead (PLONG)—input/output 

Pointer to a LONG. The number of bytes read into pszFormatName is 
returned, representing the length of the format name. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 
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Return Values 


rc (ULONG) — return value 

MMIOJ3UCCESS MMIO.ERROR 

MMIOERR_INVALID_PARAMETER 

Remarks 

An application can use this API in conjunction with the mmioIdentifyFile 
API to determine the size of the buffer needed to supply this call. 
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mmioGetFormats 


mmioGetFormats 

Provides a list of all format I/O procedures available for use. 


//define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmioGetFormats( PMMFORMATINFO pmmformatinfo, 
LONG INumFormats, 

PVOID pFormatlnfoList, 

PLONG piFormatsRead, 

ULONG ulReserved, 

ULONG ulFlags ) 


Parameters 

pmmformatinfo (PMMFORMATINFO)—input 

A pointer to a MMFORMATINFO structure that might have optionally set 
the fccIOProc field (FOURCC code) or ulMediaType field (Multimedia data 
type). These two field provide the search criteria for matching an MMFOR¬ 
MATINFO structure. If both of these fields are NULL, then all I/O 
Procedure MMFORMATINFO structures are returned, provided enough 
space is allocated for in the buffer pointed to by the pFormatlnfoList para¬ 
meter. 

INumFormats (LONG)—input 

The maximum number of MMFORMATINFO structures that can be 
returned in the pFormatlnfoList parameter buffer. 

pFormatlnfoList (PVOID)—input/output 

Pointer to a buffer that will be filled in with a list of matched MMFOR¬ 
MATINFO structures. The application needs to allocate enough memory to 
hold the requested number of structures. 

plformatsRead (PLONG)—input/output 

Pointer to a LONG data type. Returns the number of formats that were 
returned in the pFormatlnfoList parameter buffer. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 
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ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

re (ULONG)—return value 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOJERROR MMIOERR_INTERNAL_SYSTEM 

Remarks 

An application can use the mmioQueryFormatCount API to query the num¬ 
ber of formats supported. It can then call mmioGetFormats with the correct 
size of pFormatlnfoList to obtain descriptive information about the file formats 
supported by currently installed I/O procedures. This listing will assist users in 
finding out which data types can be output to a device. mmioGetF ormats can 
also be used to query the number of file formats supported. To allocate the 
buffer for the file formats supported, multiply the number of formats by the 
size of the MMFORMATINFO structure (the MMFORMATINFO structures 
are all the same size). 
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mmioGetHeader 


mmioGetHeader 

Requests a media specific header for an open file. The specific header depends 
on the media type of the file and current track setting, in the case of multiple 
tracks. This header can be a RAW header or a translated header. 


#define INCL_MMI00S2 
^include <os2me.h> 

ULONG mmioGetHeader( HMMIO hmmio, 

PVOID pHeader, 

LONG 1HeaderLength, 
PLONG plBytesRead, 
ULONG ulReserved, 
ULONG ulFlags ); 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pHeader (PVOID)—input 

Pointer to a header structure. This structure is filled in by the I/O Procedure. 
If the MMIO_TRANSLATEHEADER flag was set in the ulTranslate field of 
MMIOINFO on the mmioOpen API, then the header returned is one associ¬ 
ated with the standard presentation format for that particular multimedia 
data type (media type). Each media type (refer to the ulMediaType field of the 
MMIOFORMATINFO structure) has a different standard presentation 
header. 

The I/O Procedure is expected to transpose native header information, as 
read from the file, into the standard presentation format header before pass¬ 
ing the data to the caller. The currently defined values for each media type 
( ulMediaType ) and their respective media structures are as follows: 

MMIO_MEDIATYPE_IMAGE —The data represents a still image. Images 
use MMIMAGEHEADER as the media structure. 

MMIO_MEDIATYPE_AUDIO —The data represents digital audio. Digital- 
audio data streams use MMAUDIOHEADER as the media structure. 
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MMIO_MEDIATYPE_MIDI —The data represents MIDI streams. MIDI 
data streams use MMMIDIHEADER as the media structure. 

MMIO_MEDIATYPE_DIGITALVIDEO —The data represents digital 
video. Digital video data streams use MMVIDEOHEADER as the media 
structure. 

]\IMIO_MEDIATYPE_MOVIE —The data represents a movie. Movie data 
use MMMOVIEHEADER as the media structure. 

IF MMIO_NOTRANSLATE flag was specified on the open (default case), 
then the file format native header is returned. 

lHeaderLength (LONG)—input 

The size, in bytes, of the header structure. 

plBytesRead (PLONG)—input/output 

Returns the number of bytes read to the header structure. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

MMIO.SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOJERROR MMIOERR_INTERNAL_SYSTEM 

MMIOERR_SEEK_F AILED 


Remarks 

The plBytesRead parameter value might differ from the actual number of bytes 
read from the file in the case of translations. 

Compound-files are not supported by the mmioGetHeader API. Only non- 
compound-files and compound-file elements are supported. 

This API can be used in conjunction with the mmioSet API to query specific 
track headers from a multiple track movie file. 
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mmioGetlnfo 


mmioGetlnfo 

Retrieves information from the file I/O buffer to a file opened for buffered I/O. 


#define INCL_MMI00S2 
//include <os2me.h> 

USHORT mmioGetInfo( HMMIO hmmio, 

PMMIOINFO pmmioinfo, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 

pmmioinfo (PMMIOINFO)—input/output 

A caller-allocated MMIOINFO buffer that is to receive information about 
the open file. See the description of the mmioOpen API for information 
about how the fields are interpreted. 

usFlags (USHORT)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (USHORT)—return value 

MMIO.SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOERR_INVALID_HANDLE MMIOERRJJNBUFFERED 

MMIOERR_READ_FAILED MMIO_SEEK_FAILED 

Remarks 

An application can access the I/O buffer directly, as follows: 

• Call mmioGetlnfo. The pchNext field of the MMIOINFO structure is a 
pointer to the next byte that can be read from or written to. 



602 Developing Multimedia Applications Under OS/2 


• To read directly from the buffer, the application reads from the location 
pointed to by pchNext up to (but not including) the location pointed to by the 
pchEndRead pointer. 

• To write directly to the buffer, the application writes to the location pointed 
to by pchNext up to (but not including) the location pointed to by the 
pchEndWrite pointer. 

• Once pchNext is modified, do not call any MMIO APIs (except for 
mmioAdvance) until mmioSetlnfo is called. In particular, do not call 
mmioRead and mmioWrite. Once mmioSetlnfo is called, the caller must 
stop accessing the I/O buffer directly and revert to using mmioRead and 
mmioWrite to read and write the file. 

• To read beyond pchEndRead or write beyond pchEndWrite , call 
mmioAdvance to read and write contents of the next full buffer. 
mmioAdvance will adjust various fields in your MMIOINFO structure, 
including pchNext, pchEndRead, and pchEndWrite. 

• Before calling mmioAdvance or mmioSetlnfo, make sure you set the 
MMIO_DIRTY flag of the ulFlags field of MMIOINFO structure passed in 
pmmioinfo parameter if you have written to the buffer. Otherwise, the 
buffer contents will not get written to the disk. 

• The caller must not move pchNext backward. No fields other than pchNext 
and the MMIO_DIRTY flag of ulFlags are to be modified. 
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mmioGetLastError 


mmioGetLastError 

Returns the last error condition stored in the ulErrorRet field of the MMIOIN- 
FO structure that might contain additional information for the analysis of the 
last error routine. 


//define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmioGetLastError( HMMIO hmmio ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 

Return Values 

re (ULONG)—return value 

Return code indicating success or type of failure: 

' MMIOERR_INVALID_HANDLE 


Remarks 

The user can call mmioGetLastError for those APIs that return only 
MMIO_ERROR or MMIO_CF_FAILURE, and obtain additional information 
about the failing condition from the ulErrorRet field of the MMIOINFO struc¬ 
ture. If ulErrorRet does not contain an MMIO error code, it contains an OS/2 
error code or 0. 
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mmioldentifyFile 


mmioldentifyFile 

Determines (if possible) the format of a file by either using the file name or 
querying currently installed I/O procedures to see which I/O procedure can 
understand and process the specified file. 


#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioldentifyFi1e( PSZ pszFileName, 

PMMIOINFO pmmioinfo, 
PMMFORMATINFO pmmformatinfo, 
PFOURCC pfccStorageSystem, 
ULONG ulReserved, 

ULONG ulFlags ) 


Parameters 

pszFileName (PSZ)—input 
The name of the file to identify, 
pmmioinfo (PMMIOINFO)—input 

Pointer to an MMIOINFO structure. This parameter is needed when a 
RIFF compound-file element is not completely valid. Normally this is NULL. 

pmmformatinfo (PMMFORMATINFO)—input/output 

Pointer to the MMFORMATINFO structure that, upon return from this 
API, contains information about the I/O procedure that handles this format. 
This includes the media type, such as image, audio, and compound, and the 
I/O procedure FOURCC code value that can then be used to open the file for 
further processing. This is returned only upon successful completion. 

pfccStorageSystem (PFOURCC)—input/output 

A pointer that, upon return from the function, contains the FOURCC code 
of the storage system. 

ulReserved (ULONG)—input 

A reserved ULONG. 

ulFlags (ULONG)—input 
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The following flags are defined: 

MMIO_FORCE_IDENTIFY_SS —Forces the identification of a storage sys¬ 
tem by ignoring the file name and actually checking the MMIO Manager’s 
I/O procedure list. 

MMIO_FORCE_IDENTIFY_FF —Forces the identification of a file format 
by ignoring the file name and actually checking the MMIO Manager’s I/O 
procedure list. 

Return Values 

re (ULONG)—return value 

Return codes indicating success or type of failure. For information about 
DOS File errors, use the mmioGetLasterror API. 

MMIO.SUCCESS MMIOERR_INVALID_PARAMETER 

MMIO_ERROR MMIOERR_INTERNAL_SYSTEM 


Remarks 

The order of I/O procedures to be searched is controlled by the 
MMPMMMIO.INI file; the order in which they are installed is controlled by 
mmioInstalllOProc . The last installed procedure is first in the list. The order 
of search can be controlled based on the formats that are normally used. The 
default match will be the DOS I/O procedure. 
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mmioldentifyStorageSystem 


mmioldentifyStorageSystem 

Identifies the storage system that contains the media data object. 


#define INCL_MMI00S2 
#i include <os2me.h> 

ULONG mmioldentifyStorageSystem( PSZ pszFileName, 

PMMIOINFO pmmioinfo, 

PFOURCC pfccStorageSystem ) 


Parameters 

pszFileName (PSZ)—input 
The file name to be identified, 
pmmioinfo (PMMIOINFO)—input 

A pointer to the MMIOINFO buffer that might contain additional data. 
Normally this is NULL, but it is needed for compound-file elements when 
they are not fully qualified. 

pfccStorageSystem (PFOURCC)—input/output 

A pointer to the FOURCC code of the storage system that gets returned 
upon successful completion. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure. For more information 
about DOS File errors, use the mmioGetLastError API. 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOJERROR MMIOERR_INTERNAL_SYSTEM 
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Remarks 

mmioIdentifyStorageSystem processes the MMIO internal I/O procedure list 
to determine if the file name specified is of type MMIO_IOPROC_STOR- 
AGESYSTEM. If it is, an MMIOMJDENTIFYFILE message is sent to the 
I/O procedure to see if it can identify the data object. The pfccStorageSystem 
parameter contains the FOURCC code of the I/O procedure that successfully 
identified the data object. 
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mmiolniFileCODEC 


mmiolniFileCODEC 

Modifies the initialization file (MMPMMMIO.INI) for MMIO services. It adds, 
replaces, removes, or finds a CODEC procedure in the MMPMMMIO.INI file. 


#define INCL_MMI00S2 
#define INCL_MMI0_C0DEC 
#iinclude <os2me.h> 

ULONG mmiolniFi1eC0DEC( PCODECINIFILEINFO pCODECIniFi1elnfo, 

ULONG ulFlags ) 


Parameters 

pCODECIniFilelnfo (PCODECINIFILEINFO)—input 

A pointer to the CODECINIFILEINFO structure that contains the file for¬ 
mat FOURCC, compression type, compression subtype, CODEC DLL, 
name, entry procedure name, and other CODEC Procedure information. 

ulFlags (ULONG)—input 

MMIO JNSTALLPROC— Adds a CODEC Proc to the end of the MMPMM¬ 
MIO.INI file. If an existing entry in the table matches the new entry, the 
new entry replaces the existing entry. An entry match is determined by 
specifying 0 or more of the match flags. If none are specified, the default is 
to match on the FOURCC. 

MMIO_REMOVEPROC —Deletes a matching entry from the MMPMM¬ 
MIO.INI file. An entry match is determined by specifying 0 or more of the 
match flags. If none are specified, the default is to match on the FOURCC. 

MMIO_FINDPROC —Finds a matching entry from the MMPMMMIO.INI 
file. This fills in the remainder of the CODECINIFILEINFO. An entry 
match is determined by specifying 0 or more of the match flags. If none are 
specified, the default is to match on the FOURCC. 

Note: If MMIOJMATCHFIRST is set, then MMIO_FINDPROC does not 
default to the FOURCC. 
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MMIO.MATCHFIRST— Finds the first entry in the MMPMMMIO.INI file 
if no match flags are specified. Otherwise, it finds the first entry that match¬ 
es the contents of the fields specified by the match flags. In either case, a 
CODECINIFILEINFO structure is returned in the pCODECIniFilelnfo 
parameter. 

MMIO_MATCHNEXT —If no match flags are specified, this finds the next 
CODEC entry in the MMPMMMIO.INI file following the entry passed in 
pCODECIniFilelnfo parameter. If match flags are specified, this finds the 
next entry that matches the search criteria specified by the flags. In either 
case, a CODECINIFILEINFO structure is returned in the 
pCODECIniFilelnfo parameter. 

MMIO_MATCHCOMPRESSTYPE —Uses compression type 

(;ulCompressType field of CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHHWID —Uses hardware ID ( szHWID field of 
CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHCAPSFLAGS —Uses capability flags ( ulCapsFlags field of 
CODECINIFILEINFO) as a search criteria. Note that this search is not 
based on the exact match. If the target entry contains the flags, the match is 
satisfied. 

MMIOJV1ATCHFOURCC— Uses the FOURCC code {fee field of 
CODECINIFILEINFO) as a search criteria. 

MMIO.MATCHDLL— Uses the DLL Name (szDLLName field of 
CODECINIFILEINFO) as a search criteria. 

MMIO_MATCHPROCEDURENAME —Uses the case-sensitive Procedure 
Name ( szProcName field of CODECINIFILEINFO) as a search criteria. 

MMIO_FULLPATH —Uses the drive or path given with the DLL name 
{szDLLName field of CODECINIFILEINFO), otherwise uses only the base 
file name. This allows DLLs with the same base name to be loaded from dif¬ 
ferent directories. 


Return Values 


rc (ULONG)—return value 

MMIO.SUCCESS 

MMIOJERROR 

MMIO_INVA[JD_PARAMETER 

MMIOERR_INTERNAL_SYSTEM 

MMIOERR_NO_CORE 


MMIOERRJMOPEN 
MMIOERR_INVALID_DLLNAME 
MMIOERR_INVALID_PROCEDURENAME 
MIOERR_MATCH_NOT_FOUND 
MMIOERR_C ODE C_N OT_SUPPORTED 
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Remarks 


The MMPMMMIO.INI file is in the directory specified in the MMBASE envi¬ 
ronment variable. 

The DLL name ( szDLLName ) specified in the CODECINIFILEINFO struc¬ 
ture must follow the same naming conventions as the DosLoadModule API. If 
the DLL or procedure name is invalid, an error is returned. 

In a deletion, the entry is removed, and the entire file is rewritten to prevent it 
from growing with deleted entries. This is due to the way OS/2 APIs delete 
entries from INI files. Deleted entries are not reused. 
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mmiolniFileHandler 


mmiolniFileHandler 

Adds, replaces, removes, or finds an I/O procedure in the initialization file 
(MMPMMMIO.INI). 


#define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmiolniFi1eHandler( PMMINIFILEINFO pmminifi1einfo, 

ULONG ulFlags ) 


Parameters 

pmminifileinfo (PMMINIFILEINFO)—input 

A pointer to the MMINIFILEINFO structure that contains the FOURCC 
code, DLL name, and the name of the I/O procedure. 

ulFlags (ULONG)—input 

MMIO_INSTALLPROC —Adds an I/O procedure to the end of the MMPM¬ 
MMIO.INI file. If an existing entry in the table matches the new entry, the 
new entry replaces the existing entry. An entry match is determined by 
specifying 0 or more of the match flags. If none are specified, the default is 
to match on the FOURCC code. 

MMIO_REMOVEPROC —Deletes a matching entry from the 
MMPMMIO.INI file. An entry match is determined by specifying 0 or more 
of the match flags. If none are specified, the default is to match on the 
FOURCC code. 

MMIO_FINDPROC —Finds a matching entry from the MMPMMMIO.INI 
file. This fills the remainder of the MMINIFILEINFO structure passed in 
the pmminifileinfo parameter. An entry match is determined by specifying 0 
or more of the match flags. If none are specified, the default is to match on 

the FOURCC. 

Note: If MMIOJVIATCHFIRST is set, then MMIO.FINDPROC does not 
default to the FOURCC. 
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MMIOJV1ATCHFIRST —Finds the first entry in the MMPMMMIO.INI file 
if no match flags are specified. Otherwise, it finds the first entry that match¬ 
es the contents of the fields specified by the match flags. In either case, the 
MMINIFILEINFO structure is returned. 

MMIOJMATCHNEXT— Finds the next entry in the MMPMMMIO.INI file 
following the entry (MMINIFILEINFO structure) passed in pmminifileinfo 
parameter if no match flags are specified. If match flags are specified, this 
find the next entry that matches the search criteria specified by the flags. In 
either case, the MMINIFILEINFO structure is returned. 

MMIO.MATCHFOURCC— Uses the FOURCC code (fccIOProc field of 
MMINIFILEINFO structure) as a search criteria. 

MMIO.MATCHDLL— Uses the DLL Name (szDLLNameO field of 
MMINIFILEINFO structure) as a search criteria. 

MMIO_MATCHPROCEDURENAME —Use the case-sensitive procedure 
name (szProcNameO field of MMINIFILEINFO structure) as a search crite¬ 
ria. 

MMIOJFULLPATH —Uses the drive or path given with the DLL name 
0 szDLLNameO field of MMINIFILEINFO structure), otherwise use only the 
base file name. This allows DLLs with the same base name to be loaded 
from different directories. 


Return Values 

rc (ULONG)—return value 

MMIO_SUCCESS MMIOERR_NO_CORE 

MMIO_ERROR MMIOERR_INI_OPEN 

MMIOERR_INVALID_PARAMETER MMIOERR_INVALID_DLLNAME 
MmOERRJNTERNAL.SYSTEM 

RR_MATCH_NOT_FOUND MmOERR_INVALID_PROCEDURENAME 

Remarks 

The MMPMMMIO.INI file is in the directory specified in the MMBASE envi¬ 
ronment variable. 

The DLL name (szDLLName field) specified in the MMINIFILEINFO struc¬ 
ture must follow the same naming conventions as the DosLoadModule API. If 
the DLL or procedure name is invalid, an error is returned. 
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Any changes this API makes to the MMPMMMIO.INI file do not affect the 
MMIO internal data structures until the next time the DLL is loaded. This 
means that in the case of an addition, for example, the I/O procedure added is 
not active until the next time the MMIO.DLL is loaded. 

In a deletion, the entry is removed and the entire file is rewritten to prevent it 
from growing with deleted entries. This is due to the way OS/2 APIs handle 
deleting entries from INI files in general. They do not reuse deleted entries. 

If an error occurs during the loading of MMIO.DLL because the I/O procedure 
or procedure name cannot be validated, MMIO.DLL will still be loaded, but 
that particular I/O procedure will not be linked. The user must program for 
such situations. 

Note: When MMIO services builds its internal structures for the I/O proce¬ 
dures, it processes the MMPMMMIO.INI file as a stack. The result is, the last 
I/O procedure in the file is the first one called during processing. Thus, in the 
MMPMMMIO.INI file, enter last those I/O procedures to be processed first. 
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mmiolnstalllOProc 


mmiolnstalllOProc 

Installs an I/O procedure in the MMIO I/O Procedure table, removes an I/O 
procedure from the table, or finds an I/O procedure when given its FOURCC 
identifier. 


#define INCL_MMI00S2 
#include <os2me.h> 

PMMIOPROC mmiolnstal1IOProcC FOURCC fccIOProc, 

PMMIOPROC plOProc, 
ULONG ulFlags ) 


Parameters 

fccIOProc (FOURCC)—input 

The four-character code of the I/O procedure to install, remove, or search for. 
plOProc (PMMIOPROC)—input 

If this API is being called to install an I/O procedure, this field must contain 
the address of the I/O procedure entry point. Otherwise, this field is NULL. 

ulFlags (ULONG)—input 

Only one of the following flags can be set: 

MMIO_INSTALLPROC —Installs an I/O procedure with the entry point 
specified in the plOProc parameter and the FOURCC in the fccIOProc 
parameter. 

MMIO_REMOVEPROC —Removes an I/O procedure that has the FOUR¬ 
CC specified in the fccIOProc parameter from the table of installed I/O pro¬ 
cedures. 

MMIO_FINDPROC —Finds a previously installed I/O procedure with the 
FOURCC specified in the fccIOProc parameter. 
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Return Values 

rc (PMMIOPROC)—return value 

Upon successful completion, this API returns the address of the I/O proce¬ 
dure that was installed, removed, or searched. If a failure occurs, NULL is 
returned. 


Remarks 

Installing an I/O procedure in the MMIO I/O procedure table allows 
mmioOpen to call that procedure if the file name given to mmioOpen is spec¬ 
ified as being a FOURCC of the same type as the fccIOProc parameter. For 
example, if you install a hypothetical I/O procedure with the fccIOProc para¬ 
meter equal to XYZ, and then call mmioOpen to open the file FOO.XYZ, set¬ 
ting MMIOINIFO structure, fccIOProc field = XYZ, your I/O procedure is 
called to open and perform I/O on FOO.XYZ. 

mmioInstalllOProc maintains a separate list of installed I/O procedures for 
each OS/2 application that uses MMIO services. If application X (or a DLL that 
application X calls) installs an I/O procedure identified as ABC, and applica¬ 
tion Y (or a DLL that Y calls) installs another I/O procedure identified as ABC, 
then MMIO service keeps separate entries in the I/O procedure table. 
Therefore, different applications can use the same I/O procedure identifier for 
different I/O procedures without conflict. Also, if an I/O procedure is imple¬ 
mented in a DLL and shared among several applications, each application 
must call mmioInstalllOProc individually (or get the DLL to call it for the 
application), once to install the I/O procedure, and once to remove it from the 
table. 

If an application calls mmioInstalllOProc more than once to register the 
same I/O procedure, then mmioInstalllOProc must be called once with 
MMIO_REMOVEPROC for each time it is called with MMIO_INSTALL- 
PROC. 

mmioInstalllOProc will not prevent an application from installing two differ¬ 
ent I/O procedures with the same identifier, or installing an I/O procedure with 
the same identifier as a built-in I/O procedure (DOS, MEM, or BND). The most 
recently installed procedure takes precedence, and is the first one to get 
removed by MMIO_REMOVEPROC. 
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mmioLoadCODECProc 


mmioLoadCODECProc 

Loads the CODEC procedure and returns the entry point. 


#define INCL_MMI00S2 
#define INCL_MMI0_C0DEC 
#include <os2me.h> 

PCODECPROC mmioLoadCODECProc( PCODECINIFILEINFO pCODECIniFi1elnfo, 

PHMODULE phMod, 

ULONG ulFlags ) 


Parameters 

pCODECIniFilelnfo (PCODECINIFILEINFO)—input 

A pointer to a structure containing the CODEC information. The search 
parameters used to load the CODEC Procedure are specified in ulFlags 
parameter. 

phMod (PHMODULE)—input/output 

Pointer to the returned module handle of the loaded CODEC Procedure. 
ulFlags (ULONG)—input 

Specifies options for the operation. Contains one of the following flags: 

MMIO.MATCHCOMPRESSTYPE— Uses compression type 
(ulCompressType field of CODECINIFILEINFO) as search criteria for 
loading the CODEC Procedure. 

MMXO_MATCHCOMPRESSUBTYPE —Uses the compression subtype 
(:ulCompressSubType field of CODECINIFILEINFO) as search criteria for 
loading the CODEC Procedure. 

MMIO_MATCHHWID —Uses the hardware ID (szHWIDO field of 
CODECINIFILEINFO) as search criteria for loading the CODEC 
Procedure. 

MMIOJV1ATCHCAPSFLAGS —Uses the capability flags (ulCapsFlags 
field of CODECINIFILEINFO) as search criteria for loading the CODEC 
Procedure. This is not based on an exact match. If the target entry contains 
the flags, the match is satisfied. 
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MMIO_SKIPMATCH —Skips the search and loads the CODEC Procedure 
using the DLL name (szDLLNameO) and Procedure name ( szProcNameO) 
specified in the CODECINIFILEINFO structure. 

MMIO.MATCHDLL— Uses the DLL Name (szDLLNameO field of 
CODECINIFILEINFO) as search criteria for loading the CODEC 
Procedure. 

MMIO_MATCHFOURCC —Uses the FOURCC code (fee field of 
CODECINIFILEINFO) as search criteria for loading the CODEC 
Procedure. 

MMIO_MATCHPROCEDURENAME —Uses the case sensitive procedure 
name (szProcNameO field of CODECINIFILEINFO) as search criteria for 
loading the CODEC Procedure. 

Return Values 

rc (PCODECPROC)—return value 

Upon successful completion, this API returns the address of the CODEC 
Proc that has been loaded. If a failure occurs, NULL is returned. 


Remarks 


If none of the flags are specified, the default is to match on the FOURCC. 
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mmioOpen 


mmioOpen 

Opens a file and returns an MMIO handle. 


^define INCL_MMI00S2 
#include <os2me.h> 

HMMIO mmioOpen( PSZ pszFileName, 

PMMIOINFO pmmioinfo, 
ULONG ulOpenFlags ) 


Parameters 

pszFileName (PSZ)—input 

The name of the file to open. If fccIOProc field of MMIOINFO is NULL, this 

API looks at the pszFileName parameter to determine what kind of file to 

open, as follows: 

• If the pszFileName parameter does not contain a plus (+), the name is 
assumed to be that of a DOS file, which is opened using the file system 
file open process. 

• If the file name is of the form ABC.EXT + ELEMENTNAME, the exten¬ 
sion EXT is assumed to identify an installed I/O procedure that is called 
to perform I/O on the file. If the extension is BND, the system-provided 
BND I/O procedure processes the open. Note also that the ELEMENT- 
NAME could be of the form right to left, so the first I/O procedure called 
belongs to the rightmost extension name that is followed by the +. The I/O 
procedure must already be installed and be able to further parse the file 
name, if required. The trailing separator character is stripped off by 
mmioOpen and is not passed to the I/O procedure. 

• If the pszFileName parameter is NULL, then the aullnfo[0] field of 
MMIOINFO contains the DOS file handle, and I/O is performed on that 
file handle. The MMIO offset is the same as the DOS offset when this API 
is called. 
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• The pszFileName parameter cannot be longer than 260 bytes, including 
the terminating NULL, for a fully-qualified path name, or 256 bytes for 
an individual component name, including the terminating NULL. 

pmmioinfo (PMMIOINFO)—input 

A pointer to a caller-provided MMIOINFO structure containing extra para¬ 
meters used by mmioOpen. The pmmioinfo parameter can be NULL if the 
default values of the fields of pmmioinfo are sufficient. The applicable fields 
are described under the ulOpenFlags parameter description. All unused 
fields must be set to 0, including reserved fields (the easiest way to do this is 
to fill the structure with null bytes before completing in the desired fields). 

The aulInfo[3] field of MMIOINFO can contain a media type that restricts 
the open to I/O procedures of that type. If those I/O procedures cannot open 
the file, a NULL value is returned. 

ulOpenFlags (ULONG)—input 

Contains one or more of the following flags: 

Note: The MMIO.READ, MMIO.WRITE, and MMIO_READWRITE 

flags are mutually exclusive. 

MMIO_READ —Opens the file for reading only. This is the default behavior 
if MMIO_WRITE and MMIO_READWRITE are not specified. However, 
the flag is not automatically set in the default case. 

MMIO_WRITE —Opens the file for writing. You should not read from a file 
opened in this way. 

MMIO_READWRITE —Opens the file for both reading and writing. 

MMIO_BUFFSHARED —Requests that if MMIO service allocates the I/O 
buffer, it does so from shared memory. 

MMIO_VERTBAR —Requests that the vertical bar symbol (I) rather than 
the plus sign (+) be used as a file separator. 

MMIO_EXCLUSIVE —Opens the file with exclusive mode, denying other 
processes both read and write access to the file. This API will fail if the file 
has been opened in any other mode for read or write access, even by the cur¬ 
rent process. 

MMIO_DENYWRITE —Opens the file and denies other processes write 
access. This API will fail if the file has been opened in compatibility or for 
write access by any other process. 
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MMIO_DENYREAD —Opens the file and denies other processes read 
access. This API will fail if the file has been opened in compatibility or for 
read access by any other process. 

MMIO_DENYNONE —Opens the file and denies other processes read 
access. This API will fail if the file has been opened in compatibility or for 
read access by any other process. This is the default if no share mode flags 
are defined. 

MMXO_CREATE —Directs this API to create a new file. If the file already 
exists, it is truncated to 0 length. For a memory file, this flag indicates the 
end of the file is initially at the start of the buffer. 

MMIO_DELETE —Directs this API to delete the file. The pszFileName 
parameter should not be NULL. The return value will be TRUE (set to 
hmmio) if the file was deleted successfully; FALSE otherwise. Do not call 
mmioClose if MMXO_DELETE has been specified. All other flags are 
ignored if MMIO_DELETE is specified. 

MMIO_ALLOCBUF —Directs this API to allocate an I/O buffer. If 
cchBuffer field of MMXOINFO structure is 0, then a default buffer size 
(specified by the constant MMIO_DEFAULTBUFFER) is used. If the caller 
provides an I/O buffer, then MMIO_ALLOCBUF should not be specified. 

MMIO_APPEND —Directs this API to allow appending to the end of the 
file. This will cause the logical file pointer to be positioned at the end of file 
when the open process completes. The open fails if both MMIO_CREATE 
and MMIO.APPEND are set. In the case of a BND element, this flag 
allows the element to expand past its existing and rewriting it at the end of 
a compound-file resource group (CGRP). 

MMIO_NOXDENTIFY —Directs this API to directly open the file without 
trying to automatically identify the file. An automatic identify is the default 
for this API. 

Return Values 

re (HMMIO)—return value 

A handle is returned to use with further calls to MMIO APIs to perform I/O. 
This handle is not a file system handle. Do not use this with such operations 
as OS/2 file system reads or writes. 
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NULL is returned if the file cannot be opened. See the exception for the pre¬ 
ceding ulOpenFlags parameter flag MMIO_DELETE. If pmmioinfo para¬ 
meter is not NULL, its ulErrorRet field will contain extended error informa¬ 
tion returned by the I/O procedure. If delete fails, ulErrorRet field contains 
MMIOERR_DELETE_FAILED. The error return can also be queried by 
calling the mmioGetLastError API. 


Remarks 

If the pmmioinfo parameter is provided the following fields must be filled in by 
the caller as described: 

fccIOProc —If this field is not NULL, it is the four-character code of an 
installed I/O procedure that will handle I/O. If the fccIOProc and plOProc 
fields are NULL, mmioOpen determines which I/O procedure to use based 
on the syntax of pszFileName parameter. If fccIOProc is NULL, but plOProc 
is not NULL, the custom I/O procedure specified by plOProc is used. This 
I/O procedure does not need to be installed using the mmioInstalllOProc 
API. 

The following I/O procedure identifiers are defined: 

FOURCC_DOS — pszFileName is assumed to be either the name of a DOS 
file, or aulInfofO] contains the DOS file handle of an open file. 

FOURCC_BND —A RIFF compound file element is opened. This API calls 
mmioCFOpen internally if necessary to read the CTOC into memory before 
the element can be accessed. If MMIO_CREATE or MMIO_APPEND is 
specified when opening an element, the system automatically accesses the 
element as exclusive until the element is closed. 

FOURCC_MEM —A memory file is opened. The pszFileName parameter 
should be NULL. There are two ways to set up a memory file: 

1. The pchBuffer field points to a caller-supplied memory buffer, and the 
cchBuffer field indicates the size of the buffer. The memory file can be 
read and written like an ordinary file, but the file can not be expand¬ 
ed larger than the number of bytes specified in cchBuffer. If the 
MMIO_CREATE flag is specified, the end of the file is initially at the 
beginning of the buffer. If MMIO_CREATE is NULL, the user speci¬ 
fies in the aullnfofl] field the number of bytes of data in the memory 
buffer. For the default case, where aul!nfo[l] is 0, the end of the file is 
set to the end of the buffer. 
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2. This API can allocate the memory buffer for the memory file. The 
cchBuffer field is the desired initial size of the memory I/O buffer. The 
aullnfo[0] field must be the number of bytes by which to expand the 
memory file if the initial buffer becomes filled. The MMIO_CREATE 
flag must be specified. The end of the file is initially at the beginning 
of the buffer, and if the memory file must be expanded, it is expanded 
at least aullnfo[0] bytes at a time. If aullnfo[0] is 0, the buffer cannot 
expand. There is no default for cchBuffer when used to open a memo¬ 
ry file. 

The plOProc field uses a custom I/O procedure defined in this field. Set the 
fccIOProc field to NULL, and set plOProc must be NULL. 

The cchBuffer field specifies the size of the memory buffer as an I/O Buffer or 
to use as a memory file. See descriptions of pchBuffer under MMIOINFO data 
structure description and the MMIO_ALLOCBUF flag for more information. 

The pchBuffer field points to a caller-provided memory buffer to use as an I/O 
Buffer or as a memory file. The cchBuffer field must be the size of the buffer. If 
the caller-provided memory buffer is not provided, pchBuffer must be NULL. 

To open a memory file that performs I/O on an already allocated memory 
buffer, set the pszFileName parameter to NULL, fccIOProc field to FOUR- 
CC_MEM, pchBuffer field to point at the memory buffer, cchBuffer field to the 
size of the memory buffer, ulOpenFlags parameter to MMIOJREADWRITE 
(plus MMIO_CREATE if the memory file is initially empty), and set all other 
fields of pmmioinfo MMIOINFO structure to zero. 

A system-allocated memory buffer must be opened as MMIO_RE AD WRITE, 
which is the default for that case. If this does not happen, the open-a-memory 
file process fails. 

If both a user buffer is specified and an expansion size is requested, the open-a- 
memory file process fails because it is not possible to later expand the buffer 
size in this situation. 


MMIO handles (HMMIO) are unique to a process. 
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mmioQueryCODECName 


mmioQueryCODECName 

Returns the CODEC procedure name. 


//define INCL_MMI00S2 
//define INCL_MMI0_C0DEC 
//include <os2me.h> 

ULONG mmioQueryCODECName( PCODECINIFILEINFO pCODECIniFi1einfo, 

PSZ pszCODECName, 

PULONG pulBytesRead ) 


Parameters 

pCODECIniFilelnfo (PCODECINIFILEINFO)—input 

Pointer to the CODECINIFILEINFO data structure containing the 
CODEC information. Only the following fields of this structure are used to 
identify a CODEC procedure: fee , ulCompressType , ulCompressSubType , 
szHWID, and ulCapsFlags. 

pszCODECName (PSZ)—input/output 

Pointer to the CODEC name. This API fills in the CODEC name associated 
with the specified CODEC procedure, up to pulBytesRead bytes. Ensure that 
the buffer is at least one byte long. 

pulBytesRead (PULONG)—input/output 

On input, specifies the size in bytes of the pszCODECName parameter. On 
output, returns the number of bytes read into the pszCODECName. 

Return Values 

rc (ULONG)—return value 

MMIOJ3UCCESS MMIO_ERROR 

MMIO_INVALID_PARAMETER 


Remarks 


None. 
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mmioQueryCODECNameLength 


mmioQueryCODECNameLength 

Returns the length of the CODEC procedure name. 


#define INCL_MMI00S2 
#define INCL_MMI0_C0DEC 
#include <os2me.h> 

ULONG mmioQueryCODECNameLength( PCODECINIFILEINFO pCODECIniFi1einfo, 

PULONG pulNameLength ) 


Parameters 

pCODECIniFilelnfo (PCODECINIFILEINFO)—input 

Pointer to the CODECINIFILEINFO data structure containing the 
CODEC information. Only the following fields of this structure are used to 
identify a CODEC procedure: fee, ulCompressType, ulCompressSubType, 
szHWID, and ulCapsFlags. 

pulNameLength (PULONG)—input/output 

Number of bytes in the CODEC procedure name is returned. The returned 
length does not include the NULL terminating character. 

Return Values 

rc (ULONG)—return value 

MMIOJ3UCCESS MMIOJERROR 

MMIOERR_INVALID_PARAMETER 


Remarks 


None. 
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m m ioQuery For matCou nt 


mmioQueryFormatCount 

Provides the number of I/O procedures that a match the requested format. 


#define INCI_MMI00S2 

#include <os2me.h> 

ULONG mmioQueryFormatCount( 


PMMFORMATINFO pmmformatinfo, 
PLONG piNumFormats, 

ULONG ill Reserved, 

ULONG ulFlags ) 


Parameters 

pmmformatinfo (PMMFORMATINFO)—input 

Indicates a specific I/O procedure that is to be queried on the basis of 
whether the fccIOProc field or the ulMediaType field or both are specified in 
the structure. If neither is set, all I/O procedures are counted (queried). 

plNumFormats (PLONG)—input/output 

Pointer to a PLONG. Returns the number of formats supported. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIOJSUCCESS MMIOERR_INVALID_PARAMETER 

MMIO_ERROR MMIOERR_INTERNAL_SYSTEM 
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Remarks 


An application can use this API to query the number of formats supported and 
then call mmioGetFormats with the correct size of pFormatlnfoList to obtain 
descriptive information in MMFORMATINFO structures. 
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mmioQueryHeaderLength 


mmioQueryHeaderLength 

Determines the size of the header for a specified file. The specific header 
depends on the media type of the file and the current track setting, in the case 
of multiple tracks. This header can be a RAW header or a translated header. 


#define INCL_MMI00S2 
#i include <os2me.h> 

ULONG mmioQueryHeaderLength( HMMIO hmmio, 

PLONG piHeaderLength, 
ULONG ulReserved, 
ULONG ulFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 

plHeaderLength (PLONG)—input/output 

Pointer to a LONG. The size of the header, in bytes is returned. If the 
MMIO_TRANSLATEHEADER flag was set on the ulTranslate field of the 
MMIOINFO structure on mmioOpen , it is the size of one of the standard 
headers listed below. Otherwise, it is the size of a native ( untranslated ) 
header for this type of file. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOJERROR MMIOERR_INVALID_HANDLE 

MMIOERR_SEEK_F AILED 
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Remarks 


The application calls mmioQueryHeaderLength first to determine the buffer 
size that is needed by mmioGetHeader to obtain header data. This is required 
because headers for different formats are variable in length. The header is dif¬ 
ferent for each Media Type. The currently defined values for each ulMediaType 
(MMIOINFO structure) follow: 

MMIO_MEDIATYPE_IMAGE —The data represents a still image. Images 
use MMIMAGEHEADER as the media structure. 

MMIO__MEDIATYPE_AUDIO —The data represents digital audio. Digital- 
audio data streams use MMAUDIOHEADER as the media structure. 

MMIO_MEDIATYPE_MIDI —The data represents MIDI streams. MIDI 
data streams use MIDIHEADER as the media structure. 

MMIO_MEDIATYPE_MOVIE —The data represents a movie. Movie data 
uses IY1 M MOVIEHEADER as the media structure. 
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mmioQuerylOProcModuleHandle 


mmioQuerylOProcModuleHandle 

Provides the module handle of an I/O procedure’s DLL. This handle must be 
used to retrieve resources from the DLL. 


#define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmioQueryIOProcModuleHandle( PMMIOPROC plOProc, 

PHMODULE phmodlOProc ) 


Parameters 

plOProc (PMMIOPROC)—input 

Indicates a specific entry point of an I/O procedure for which the DLL mod¬ 
ule handle is to be retrieved. 

phmodlOProc (PHMODULE)—input/output 

Pointer to a PHMODULE. Returns the module handle to the DLL. 


Return Values 


rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_SUCCESS MMIOERR_INVALID_PARAMETER 

MMIOJERROR MMIOERR_INTERNAL_SYSTEM 


Remarks 


This API can only provide the handle to the DLL if it was loaded by MMIO 
from the MMPMMMIO.INI file. 
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mmioRead 


mmioRead 

Reads a specified number of bytes from a file opened by mmioOpen. 


#define INCL_MMI00S2 
//include <os2me.h> 

LONG mmioRead( HMMIO hmmio, 

PCHAR pchBuffer, 
LONG cBytes ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pchBuffer (PCHAR)—input 
The buffer to read to. 
cBytes (LONG)—input 

The number of bytes to read from the file into pchBuffer parameter. 

Return Values 

rc (LONG)—return value 

Returns the number of bytes actually read. If no more bytes can be read 
because the end of file has been reached, 0 is returned. If an error occurs, 
MMIO_ERROR is returned. 

MMIO_ERROR —A call to mmioGetLastError may return one of the fol¬ 
lowing errors: MMIOERR_WRITE_ONLY_FILE, MMIOERR_READ_ 
FAILED, MMIOERR_WRITE_FAILED, MMIOERR_SEEK_F AILED, 
MMIOERR_INVALID_BUFFER_LENGTH, or MMIOERR_NO_ 
BUFFER_ALLOC ATED. 
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Remarks 

If the MMIO_TRANSLATEDDATA flag was in the ulTranslate field of the 
MMIOINFO structure when the file was opened, the data will be translated 
from its native encoding scheme to the encoding scheme of the standard pre¬ 
sentation format for the media type. Data in the pchBuffer parameter is 
returned to the application in the standard presentation format. 
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mmioRemoveElement 


mmioRemoveElement 

A 16-bit API to remove a specific element in a compound-file. 


#define INCL_MMI00S2 
//include <os2me.h> 

ULONG mmioRemoveElement( PSZ pszFi1eElement, 

ULONG ulFlag ) 


Parameters 

pszFileElement (PSZ)—input 

Pointer to a compound-file element name in the format: a:\path\file+ele- 
ment. 

ulFlags (ULONG)—input 

Specifies possible options. Contains 0 or the following flag: 

MMIO_RE_COMPACT —Compacts the compound-file after removing the 
element. If no element is specified but this flag is set, the compound-file will 
be compacted. If the element is specified but does not exist, no file com¬ 
paction is done. 

Return Values 

rc (ULONG)—return value 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

MMIOERR_CF_ENTRY_N OT_FOUND 
MMIOERR_INVALID_PARAMETER 


Remarks 

The mmioRemoveElement API is a high-level interface to remove an element 
from a compound-file. 
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mmioSeek 


mmioSeek 

Changes the current position for reading, writing, or both, in a file that was 
opened by mmioOpen. 


//define INCL_MMI00S2 
//include <os2me.h> 

LONG mmioSeek( HMMIO hmmio, 
LONG 1 Offset, 
LONG lOrigin ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
lOffset (LONG)—input 

Specifies an offset, in bytes, to move the file position to. 
lOrigin (LONG)—input 

Specifies how the lOffset parameter is interpreted: 

SEEK_SET —Seek to an absolute (bytes from the beginning of the file) seek 
position specified in lOffset. This is the default. 

SEEK_CUR —Seek to a relative (bytes from the current file position) seek 
position specified in lOffset. 

SEEK_END —Seek to lOffset bytes from the end of the file. 

MMIO_SEEK_IFRAME —Seek to the nearest Index or key frame based 
upon one of the previous flags.This flag is used with digital video data 
tracks/files only. 

Return Values 

rc (LONG)—return value 

Returns the new file position (in bytes) from the beginning of the file. If an 
error occurs, MMIO.ERROR is returned. 
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MMIOJERROR —A call to mmioGetLastError may return one of the fol¬ 
lowing errors: MMIOERR_SEEK_FAILED. 


Remarks 

Seeking past the end of the file does not result in an error; this API will return 
the offset of the new file position. Be careful when seeking past the end of the 
file. To determine where the end of a file is, call this API with the lOffset para¬ 
meter equal to 0 and the lOrigin parameter equal to SEEK_END. 

It is invalid to seek backwards (negative) from the beginning of the file. 

In the case of a user-supplied memory (MEM) file, a SEEK_END will seek 
from the end of the buffer, which might be different from the actual end of the 
data. 
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mmioSendMessage 


mmioSendMessage 

Sends a message to the I/O procedure associated with a file that was opened 
with mmioOpen. 


#define INCL_MMI00S2 
//include <os2me.h> 

LONG mmioSendMessage( HMMIO hmmio, 
USHORT usMsg, 
LONG IParaml, 
LONG 1Param2 ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
usMsg (USHORT)—input 
A message number. 

IParaml (LONG)—input 

Specifies additional message information. 
lParam2 (LONG)—input 

Specifies additional message information. 

Return Values 

rc (LONG)—return value 

The return code is specific to the message sent. This includes both successful 
and failed returns. 

MMIO_ERROR MMIOERR_UNSUPPORTED_MESSAGE 

Remarks 

An application can issue mmioSendMessage to send private messages to an 
installable I/O procedure. This API enables a program to call an I/O procedure 
directly (unlike system messages, which should be sent by the MMIO Manager). 
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mmioSet 


mmioSet 


This API can be used to set or query various extended information. It can asso¬ 
ciate a CODEC with an I/O procedure, set the current track for multiple track 
files, set the playing speed of a digital video, etc. 


#define INCL_MMI00S2 
#define INCL_MMI0_C0DEC 
#include <os2me.h> 


ULONG mmioSet( HMMIO hmmio, 

PMMEXTEND INFO pUserExtendmminfo, 
ULONG ulFlags) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 

pUserExtendmminfo (PMMEXTENDINFO)—input/output 

Pointer to the MLMEXTENDINFO structure. 

ulFlags (ULONG)—input 

This API contains one of the following flags: 

MMIO_SET_EXTENDEDINFO —Set the extended information. 

MMIO_QUERY_EXTENDEDINFO_BASE —Query only the information of 
the MMEXTENDINFO structure. 

MMIO_QUERY_EXTENDEDINFO_ALL —Query all extended information 
including the CODEC associated information. 

Return Values 

rc (ULONG)—return value 


Return codes indicating success or type of failure: 

MMIO.SUCCESS MMIOERRJNVALID_HANDLE 

MMIOERR_INVALID_PARAMETER 
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Remarks 

If MMIO_SET_EXTENDEDINFO is set to associate a CODEC Procedure 
with an open file, pCODECIniFilelnfo field of MMEXTENDINFO structure is 
used to identify each CODEC Procedure installed in the MMPMMMIO.INI file. 
As a result of the set, the CODEC Procedures are opened and each 
pCodecOpen structure is passed to its corresponding CODEC Procedure. 

On query, two levels of information can be returned. If 
MMIO_QUERYJEXTENDEDINFO_BASE is set, only the MMEXTENDIN¬ 
FO structure is returned. The ulNumCODECs field is the number of currently 
associated CODEC Procedures. The ulBufSize field is the buffer size for the 
second level information. If the application decides to query the second level 
information, the MMIO_QUERY_EXTENDEDINFO_ALL must be set and 
pUserExtendmminfo parameter must point to a buffer with the size equal to 
the ulBufSize field of MMEXTENDINFO structure. 

This API can associate a CODEC procedure with an MMIO handle. Typically, 
this API is used to provide CODEC information for a new file being created. 
When an existing movie file is opened, any necessary CODEC procedures are 
loaded by the I/O procedure automatically. However, there may be a need to 
change the output format (i.e., color depth) of a CODEC, and this API can be 
used for that. The default color depth is set to the display mode color depth for 
the file opened for reading (i.e., playback of a movie file). 
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mmioSetBuffer 


mmioSetBuffer 

Enable or disable buffered I/O, or change the buffer or buffer size, for a file 
that was opened using mmioOpen. 


#define INCL_MMI00S2 
#i include <os2me.h> 

USHORT mmioSetBuffer( HMMIO hmmio, 

PCHAR pchBuffer, 
LONG cBytes, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pchBuffer (PCHAR)—input 

A pointer to the caller-supplied buffer to use for buffered I/O. It can be 
NULL if the caller wants this API to allocate the buffer, or wants buffered 
I/O to be disabled. 

cBytes (LONG)—input 

The size of either the caller-supplied buffer, or the size of the buffer that the 
caller wants this API to allocate. 

usFlags (USHORT)—input 

Reserved for future use and must be set to zero. 


Return Values 


rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO.SUCCESS MMIOERR_CANNOTWRITE 

MMIOERR_INVA LID_H ANDLE MMIOERR_EEAD_FAILED 

MMIOERRJJNBUFFERED MMIOERR_SEEK_FAILED 

MMIOERR_INVALID_BUFFER_LENGTH MMIOERR_WRilE_FAILED 

MMIOERR_OUTOFMEMORY 
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Remarks 

If the pchBuffer parameter is NULL and the cchBuffer field of MMIOINFO is 
0, buffered I/O is disabled. If pchBuffer is NULL, cchBuffer is not 0, buffering 
was enabled before this API was called, and the I/O buffer was allocated by 
mmioOpen or a previous call this API, mmioSetBuffer reallocates the I/O 
buffer to be cchBuffer bytes in length. The contents of the buffer are not dis¬ 
turbed in this case (though if the buffer is shrunk, some data will be lost), 
unless the current file position is in part of the buffer that is truncated. 

If pchBuffer is NULL and cchBuffer is not 0 and buffering was disabled before 
this API was called, then mmioSetBuffer allocates an I/O buffer of cchBuffer 
bytes in length, and buffered I/O is enabled. If pchBuffer is not NULL and 
cchBuffer is not 0, then pchBuffer is assumed to be a caller-provided I/O buffer 
of cchBuffer bytes in length, which is used for buffered I/O. 
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mmioSetHeader 


mmioSetHeader 

Create or change a media specific header for a file. The specific header depends 
on the media type of the file and current track setting, in the case of multiple 
tracks. This header can be a RAW header or a translated header. 


#define INCL_MMI00S2 
#include <os2me.h> 

ULONG mmioSetHeader( HMMIO hmmio, 

PVOID pHeader, 

LONG 1HeaderLength, 
PLONG piBytesWritten, 
ULONG ulReserved, 
ULONG ulFIags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pHeader (PVOID)—input 

A pointer to a header structure. This structure is written to the file as a 
header by the I/O Procedure. If the MMIO_TRANSLATEHEADER flag 
was set in the ulTranslate field of MMIOINFO on the mmioOpen API, 
then the header written is one associated with the standard presentation 
format for that particular multimedia data type (media type). Each media 
type (refer to the ulMediaType field of the MMIOFORMATINFO structure) 
has a different standard presentation header. 

The I/O Procedure is expected to transpose a standard presentation header 
information into native header information, as written to the file. The cur¬ 
rently defined values for each media type and their respective media struc¬ 
tures are as follows: 

MMIO_MEDIATYPE_IMAGE —The data represents a still image. Images 
use MMIMAGEHEADER as the media structure. 

MMIOJMEDIATYPE_AUDIO —The data represents digital audio. Digital 
audio data streams use MMAUDIOHEADER as the media structure. 
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MMIO_MEDIATYPE_MIDI —The data represents MIDI streams. MIDI 
data streams use MIDIHEADER as the media structure. 

MMIO__MEDIATYPE_MOVIE —The data represents a movie. Movie data 
uses MMM OVIE HEADER as the media structure. 

If the MMIO_NOTRANSLATE flag was specified in the ulTranslate field of 
MMIOINFO on the mmioOpen API (default case), then the file format 
native header is returned. 

IHeaderLength (LONG)—input 

The size of the header structure(s) in bytes. 

plBytesWritten (PLONG)—input/output 

Returns the number of bytes written to the header structure. 

ulReserved (ULONG)—input 

Reserved for future use and must be set to zero. 

ulFlags (ULONG)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (ULONG)—return value 

Return code indicating success or type of failure: 

MMIO.SUCCESS 

MMIO.ERROR 

MMIOERR_INVALID_PARAMETER 

MMIOERRJNVALIDJHANDLE 

MMIOERR.SEEKJFAILED 


Remarks 

The contents of the header must represent the structure that is expected by 
the I/O procedure. It does not represent the manner in which the data will be 
saved by the I/O procedure, because the I/O procedure might translate the date 
in some manner. The plBytesWritten parameter value might differ from the 
actual number of bytes written to the file in the case of translations. 

This API can be used in conjunction with the mmioSet API to set (write) a 
specific track header into a multiple track movie file. 
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mmioSetlnfo 


mmioSetlnfo 

Changes information on a file I/O buffer of a file opened for buffered I/O. 


//define INCL_MMI00S2 
//include <os2me.h> 

USHORT mmioSetInfo( HMMIO hmmio, 

PMMIOINFO pmmioinfo, 
USHORT usFlags ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pmmioinfo (PMMIOINFO)—input 

The caller-allocated MMIOINFO buffer that was filled with information by 

mmioGetlnfo. 

usFlags (USHORT)—input 

Reserved for future use and must be set to zero. 

Return Values 

rc (USHORT)—return value 

Return codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIOERRJJNBUFFERED 

MMIOERR_INVALID_HANDLE 

MMIOERR_INVALID_PARAMETER 


Remarks 

If using buffered I/O, before calling mmioSetlnfo , make sure you set the 
MMIO_DIRTY flag in the ulFlags field of pmmioinfo if you have written to 
the buffer. Otherwise, the contents of the buffer will not be written to disk. 
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mmioStringToFOURCC 


mmioStringToFOURCC 

Converts a null-terminated string to a four-character code (FOURCC). 


#define IMCL_MMI00S2 
#include <os2me.h> 

FOURCC mmioStringToFOURCCC PSZ pszString, 

USHORT usFlags ) 


Parameters 

pszString (PSZ)—input 

The string to convert to a FOURCC. 
usFlags (USHORT)—input 

Contains 0 or the following flag: 

MMIO__TOUPPER —All the characters in the four-character code are con¬ 
verted to uppercase. 

Return Values 

rc (FOURCC)—return value 

Returns the four-character code. 


Remarks 

This API does not check to see if the pszString parameter follows any conven¬ 
tions regarding which characters to include in a FOURCC code. The string is 
simply copied to a FOURCC code and padded with blanks to the right or trun¬ 
cated to four characters, as required. 
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mmioWrite 


mmioWrite 

Writes to a file that was opened using mmioOpen. 


^define INCL_MMI00S2 
#include <os2me.h> 

LONG mmioWrite( HMMIO hmmio, 

PCHAR pchBuffer, 
LONG cBytes ) 


Parameters 

hmmio (HMMIO)—input 

The open file handle returned by mmioOpen. 
pchBuffer (PCHAK)—input 
The buffer from which to write. 
cBytes (LONG)—input 

The number of bytes to write from the pchBuffer parameter buffer to the 
file. 


Return Values 


rc (LONG)—return value 

Returns the number of bytes actually written. If an error occurs, 
MQVHOJERROR is returned and a call to mmioGetLastError may return 
one of the following errors: 

MMIOERR_READ_ONLY_FILE MMIOERR_READ_ONLY_FILE 
MMIOERR_INVALID_HANDLE MMIOERR_WRITE_F AILED 
MMIOERR_SEEK_FAILED MMIOERR_READ_F AILED 

MMIOERR_INVALID_BUFFER_LENGTH 
MMIOERR_NOJBUFFER_ALLOCATED 
MMIOERR.CANNOTWRITE. 
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Remarks 

For a memory file (MEM) that cannot expand, this API returns the number of 
bytes written. This might be fewer than requested if the end of file (EOF) is 
encountered prematurely. If the logical file pointer is past the EOF when the 
write operation is initiated, MMIO_ERROR is returned. If a pointer is at the 
end of the file (EOF), a 0 is returned indicating no bytes were written. If the 
file can expand, it will do so and write the number of bytes requested, even if 
the logical file pointer is past the EOF when the write operation was initiated. 

User buffers cannot be expanded, but system-allocated buffers can be expanded. 

Elements of a compound-file will behave similar to the way a memory file does. 
The key to whether an element can be expanded is if the element is opened 
with the MMIO_APPEND flag set. 

If the MMIO_TRANSLATEDATA flag was sent when the file was opened, the 
data is expected in the standard presentation format for the specific media 
type. The I/O procedure will translate the data from the standard representa¬ 
tion before writing to the file. 

I/O procedure Messages 

This is a list of I/O procedure messages and only messages that do not have a 
corresponding MMIO API are listed. This list does include any I/O procedure 
specific messages. This list of messages can be divided into the following cate¬ 
gories: Editing and clipboard messages, Quality of service messages, time- 
based messages, multi-track messages, and I/O procedure specific messages. 

I/O procedure messages are passed to an I/O procedure by using the 
mmioSendMessage API. This does not include CODEC procedure messages. 
All I/O procedure messages must pass a message number and a HMMIO, rep¬ 
resenting the I/O procedure to call, and two optional parameters. The reference 
shows the interface as an application would see it, not how an I/O procedure 
will actually receive the message. All messages passed on an 
mmioSendMessage go through the MMIO manager which translates the 
HMMIO into an MMIOINFO structure and passes this instead of the 
HMMIO to the I/O procedure. 
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It is possible for an application to call the entry point of an I/O procedure 
directly and by-pass the MMIO manager. In this case, the first parameter is 
always an MMIOINFO structure ( pmmioinfo ) and the second is the message 
number ( usMsg ). The mmioGetData API can be used to retrieve the contents 
of the internal MMIOINFO structure to use when calling an I/O procedure 
directly. This MMIOINFO must be used for direct calls to work correctly. The 
syntax for a direct I/O procedure call is as follows: 


typedef LONG (APIENTRY MMIOPROC) (PVOID pmmioinfo, 

USHORT usMsg, 
LONG lParml, 

LONG 1Parm2); 

typedef MMIOPROC *PMMI0PR0C; 


Editing and Clipboard Messages 

This is the list of editing and clipboard messages supported. These are optional 
messages. 
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MMIOM BEGININSERT 


MMIOM_BEGININSERT 

This message requests all subsequent mmioWrite calls insert data at the cur¬ 
rent seek position instead of overwriting the data. 

Parameters 

lParaml (LONG)—input 
This parameter is not used. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIOJERROR 


Remarks 


None. 
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MMIOM_BEGINRECORD 


MMIOM_BEGINRECORD 

This message requests all subsequent mmioWrite calls be considered one logi¬ 
cal unit by an MMIOM_UNDO or MMIOM_REDO message. 

Parameters 

lParaml (LONG) —input 
This parameter is not used. 
lParam2 (LONG) —input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or failure: 

MMIO_SUCCESS 

MMIO_ERROR 

Remarks 


None. 
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MMIOM CLEAR 


MMIOM_CLEAR 

This message is sent to an I/O procedure to request that a specified range be 
deleted from a file. The clipboard is not used for this operation. 

Parameters 

IParaml (LONG)—input 

A pointer to an MMIO_EDIT_PARMS structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIO_SUCCESS 

MMIOJERROR 


Remarks 

The media position will be at the position corresponding to the ulStartTime 
field of the MMIO_EDITJPARMS structure passed in the IParaml parame¬ 
ter. The ulDuration field of this same structure cannot be set to 0. 
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MMIOM_COPY 


MMIOM_COPY 

This message is sent to an I/O procedure to request that a specified range be 
copied to the clipboard. 

Parameters 

lParaml (LONG)—input 

A pointer to an MMIO_EDIT_PARMS structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIOJ3UCCESS 

MMIO_ERROR 


Remarks 

If data already exists in the clipboard, it is overwritten with this message call. 
The media position is not changed by this operation. ulDuration field of the 
MMIO_EDIT_PARMS structure passed in the lParaml parameter cannot be 
set to 0. 
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MMIOM CUT 


MMIOM_CUT 

This message is sent to an I/O procedure to request the specified range be 
copied to the clipboard and then deleted. 

Parameters 

lParaml (LONG)—input 

A pointer to an MMIO_EDIT_PARMS structure. 

IParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIO.SUCCESS 

MMIOJERROR 


Remarks 

If data already exists in the clipboard, it is overwritten with this message call. 
The media position will be at the position corresponding to the ulStartTime 
field of the MMIO_EDIT_PARMS structure passed in the lParaml parame¬ 
ter. The ulDuration field of this same structure cannot be set to 0. 
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MMIOM_DELETE 


MMIOM_DELETE 

This message requests that information be removed from a file. 

Parameters 

lParaml (LONG)—input 

Starting position for deletions. 
lParam2 (LONG)—input 

Length of information to be deleted. 

Returns 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

MMIO_ERROR 

Remarks 


None. 
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MMIOM ENDINSERT 


MMIOM_ENDINSERT 

This message requests that all subsequent mmioWrite calls overwrite data at 
the current seek position. This is the default mode of operation for an I/O 
procedure. 

Parameters 

lParaml (LONG)—input 
This parameter is not used. 
lParam2 (LONG)—input 
This parameter is not used. 


Returns 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

MMIO.ERROR 

Remarks 

None. 
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MMIOM_ENDRECORD 


MMIOMJNDRECORD 

This message indicates that the logical record operation has ended and that 
internal I/O procedure data structures should be updated, if necessary. 

Parameters 

lParaml (LONG)—input 
This parameter is not used. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Return codes indicating success or failure: 

MMIOJSUCCESS 

MMIO_ERROR 


Remarks 


None. 
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MMIOM PASTE 


MMIOM_PASTE 

This message is sent to an I/O procedure to request that data from the clip¬ 
board be inserted into the file at the position specified. A delete operation can 
be performed on a specified range prior to the insertion. 

Parameters 

lParaml (LONG)—input 

A pointer to an MMIO_EDIT_PARMS structure. 
lParam2 (LONG)—input 
This parameter is not used. 


Returns 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO.SUCCESS 

MMIO.ERROR 


Remarks 

Data from the clipboard is inserted into the file at the media position immedi¬ 
ately before the ulStartTime position (MMIO_EDIT_PARMS structure passed 
in the lParaml parameter). If the ulDuration field of the same structure is not 
zero, a delete operation is performed for the specified range prior to the inser¬ 
tion. After completion of this operation, the media position will be immediately 
after the pasted data. If the ulDuration field is zero, no deletion of data will 
take place before the pasting of clipboard data into the file. 
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MMIOM_REDO 


MMIOM_REDO 

This message requests that the last logical action which was undone by 

MMIOM_UNDO be redone. 

Parameters 

lParaml (LONG)—input 
This parameter is not used. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO.SUCCESS 

MMIO_ERROR 


Remarks 


None. 
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MMIOM SAVE 


MMIOM_SAVE 


This message requests that temporary changes in a file be made permanent. A 
new file name can be supplied to save the changes. 

Parameters 

lParaml (LONG)—input 

An optional pointer to a null-terminated buffer that contains a file name to 
use on the file save. 

lParam2 (LONG)—input 

This parameter is not used. 


Returns 


rc (ULONG) 

Return codes indicating success or failure: 

MMIO__SUCCESS 

MMIOJERROR 

Remarks 


None. 
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MMIOM_STATUS 


MMIOM_STATUS 

This message is used to pass MCI_STATUS messages to an I/O procedure. 

Parameters 

lParaml (LONG)—input/output 

A pointer to an MMIO_STATUS_PARMS structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIO.SUCCESS 

MMIO.ERROR 

MMIOERR_MISSING_FLAG 

MMIOERR_INVALID_ITEM_FLAG 


Remarks 


A TRUE or FALSE value is returned in the ulReturn field of a MMIO_STA- 
TUS_PARMS structure depending on the status of the item. The ulType field 
of this structure gives the MCI_FORMAT flag for the returned data when 
appropriate. Item flags for the MCI_STATUS structure are used in the ulltem 
field of the MMIO_STATUS_PARMS structure. The following flags can be 
used in the ulltem field: 

MCI_STATU S_C AN_PASTE 

MCI_STATUS_CLIPBOARD 

mci_status_can_redo 

MCI_STATU S_C AN_UNDO 
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MMIOM TEMPCHANGE 


MMIOMJEMPCHANGE 

This message requests all subsequent mmioWrite calls to an I/O procedure for 
a file be treated as temporary changes. The changes will not be saved to the 
file when closed by mmioClose unless an MMIOM__SAVE message is sent to 
the I/O procedure. 

Parameters 

IParaml (LONG)—input 

This parameter contains a pointer to a null-terminated string which has the 
name of a directory where a temporary file should be created. 

IParam2 (LONG)—input 

This parameter is not used. 


Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIOJ3UCCESS 

MMIO.ERROR 

Remarks 

None. 
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MMIOM_UNDO 


MMIOMJJNDO 

This message requests that the last logical action (MMIOMJDELETE, 
MMIOM.BEGININSERT, MMIOM_ENDINSERT, MMIOM.UNDO, 
MMIOM_REDO) be undone. 

Parameters 

lParaml (LONG) —input 
This parameter is not used. 
lParam2 (LONG) —input 
This parameter is not used. 

Returns 

rc (ULONG) 

Return codes indicating success or failure: 

MMIO_SUCCESS 

MMIOJERROR 

Remarks 


None. 
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MMIOM WINMSG 


MMIOM_WINMSG 

This message allows an application to pass PM messages from a window proce¬ 
dure to an I/O procedure. It is currently used to pass a WM_DESTROYCLIP- 
BOARD message to I/O procedure for appropriate action. It is an optional mes¬ 
sage and may not be supported by an I/O procedure; therefore any errors 
should be ignored by the caller. 

Parameters 

lParaml (LONG)—input 

A pointer to a MMIO_WINMSG structure. 
lParam2 (LONG)—input 
This parameter is not used. 


Returns 


rc (ULONG) 

Return code indicating success or failure. 

MMIOJ3UCCESS 

MMIOJERROR 

Remarks 

None. 


Quality of Service (QOS) Messages 

This is the list of audio messages supported. 
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MMIOM_BEGINSTREAM 


MMIOM_BEGINSTREAM 

Set the quality of service parameters and activate quality of service for net¬ 
work I/O. 

Parameters 

IParaml (LONG)—input 

Contains one of the following values: 

STREAM_READ —Read stream from server to client. 

STREAM_WRITE —Write stream from client to server. 
lParam2 (LONG)—input 

A pointer to a QOSInfo structure. This structure contains a variable length 
array of QOS structures. Each QOS structure contains one quality of service 
parameter, which consist of one of the following: 

The IQOSParmld field of QOS structure is one of the following: 

SERVICE.REQUEST —The requests the type service required for this 
stream. The IQOSValue field of QOS structure contains the type of service: 

GUARANTEED, DONTCARE, or DONTRESERVE. 

MAX_EE_JITTER —The number of stream buffers for handling jitter. 
Buffers needed to store a single unit of data are separate. The IQOSValue 
field of QOS structure contains the number of buffers. 

MAX_DATA_RATE —Maximum data rate in bytes per second. The 
IQOSValue field of QOS structure contains this information. 

AVG_DATA_RATE —Average data rate in bytes per second. The 
IQOSValue field of QOS structure contains this information. 
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Returns 


rc (ULONG) 

Returns codes indicating success or failure: 

MMIO SUCCESS 

MMIOERR_UNSUPPORTED_MESSAGE 

MMIOERR.QOSUNAVAILABLE 

MMIO.ERROR 


Remarks 


Some of the quality of service parameters are required on each call, if one of 
these is missing, an MMIOERR_UNSUPPORTED_MESSAGE error is 
generated. 
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MMIOM_ENDSTREAM 


MMIOM_ENDSTREAM 

This message deactivates the quality of service for network I/O. 

Parameters 

lParaml (LONG)—input 
This parameter is not used. 

IParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or failure: 

MMIO.SUCCESS 

MMIOJJNSUPPORTED 

MMIO.ERROR 

Remarks 

None. 

Time-Based Messages 

This is the list of time-based messages supported. 
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MMIOM SEEKBYTIME 


MMIOM_SEEKBYTIME 

This message requests that the file position be moved. The file position must 
be expressed in units of time not byte position within a file. 

Parameters 

lParaml (LONG)—input 

This parameter contains the signed offset to move expressed in MMTIME. 
lParam2 (LONG)—input 

Specifies how the lParaml parameter is interpreted: 

SEEK_SET —Seeks to an absolute (bytes from the beginning of the file) 
seek position specified in lParaml. This is the default. 

SEEK_CUR —Seeks to a relative (bytes from the current file position) seek 
position specified in lParaml. 

SEEK_END —Seeks to lParamlbytes from the end of the file. 

MMIO_SEEK_IFRAME —Seeks to the nearest Index or key frame preced¬ 
ing the position determined by lParaml based on one of the previous flags. 
This flag is used with digital video only data tracks/files only. 

Returns 


re (ULONG) 

Returns the new file position or in cases of error: 

MMIO.ERROR 


Remarks 

Currently, all time is expressed in terms of MMTIME time units (1/3000 of a 
second). Only some of the I/O procedures support this (MIDI and MOVIE). In 
the future this will be the preferred way to do seeks and query the current file 
position. 

Multi-Track Messages 


Give the list of multi-track messages supported. 
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MMIOM_MULTITRACKREAD 


MMIOM_MULTITRACKREAD 

This message requests that data be read from one or more tracks from a multi¬ 
ple track file. 

Parameters 

lParaml (LONG)—input/output 

Pointer to a MMMULTITRACK31EAD structure. 

!Param2 (LONG)—input 
This parameter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIO_SUCCESS 

MMIO__ERROR 

Remarks 


None. 
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MMIOM_MULTITRACKWRITE 


MMIOM_MULTITRACKWRITE 

This message requests that data for one or more tracks be written to a multiple 
track file. The data for the tracks will be interleaved by the I/O procedure. 

Parameters 

lParaml (LONG)—input/output 

Pointer to a MMMULTITRACKWRITE structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIO.ERROR 

Remarks 

None. 

AUDIO Specific Messages 

No audio messages are supported. 

MIDI Specific Messages 

No MIDI messages are supported. 

IMAGE Specific Messages 

IMAGE messages are supported. Currently no. 

MOVIE Specific Messages 

Give the list of MOVIE messages supported. 
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MMIOM_COMPRESS 


MMIOM_COMPRESS 

This message is used to compress data for a file format. 

Parameters 

lParaml (LONG)—input/output 

Pointer to the MMCOMPRESS structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO_SUCCESS 

MMIOJERROR 

Remarks 


None. 
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MMIOM DECOMPRESS 


MMIOM_DECOMPRESS 

This message is used to compress data for a file format. 

Parameters 

lParaml (LONG)—input/output 

Pointer to the MMDECOMPRESS structure. 
lParam2 (LONG)—input 
This parameter is not used. 


Returns 


rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIOJ3UCCESS 

MMIO.ERROR 


Remarks 

None. 

CODEC Procedure Messages 

This is a list of CODEC procedure messages, and these are the only interfaces 
provided for communication with a CODEC. CODEC procedure must be loaded 
and called directly, not by using mmioSendMessage . The 
mmioLoadCODECProc API will load a CODEC procedure and return the 
entry point. A call to this entry point with an MMIOM_CODEC_OPEN mes¬ 
sage will return an HCODEC, which will be used to identify the open instance 
on all other calls to the CODEC. The syntax for a direct CODEC procedure call 
is as follows: 


typedef LONG (APIENTRY CODECPROC) (PHCODEC phcodec, 

USHORT usMsg, 
LONG IParml. 

LONG 1Parm2); 

typedef CODECPROC *PC0DECPR0C; 
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MMIOM_CODEC_CLOSE 


MMIOM_CODEC_CLOSE 

This message requests that a CODEC opened by MMIOM_CODEC_OPEN be 
closed. 

Parameters 

phcodec (PHCODEC)—input 
Pointer to CODEC handle. 
usMsg (USHORT)—input 

Set to MMIOM_CODEC_CLOSE. 

IParamI (LONG)—input 
This parameter is not used. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIO.ERROR 

Remarks 


None. 
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MMIOM CODEC COMPRESS 


MMIOM_CODEC_COMPRESS 

This message requests that data be compressed by the CODEC. 

Parameters 

phcodec (PHCODEC)—input 
Pointer to CODEC handle. 
usMsg (USHORT)—input 

Set to MMIOM_CODEC_COMPRESS. 

IParamI (LONG)—input 

Pointer to a MMCOMPRESS structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Return codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIOJERROR 

Remarks 


None. 
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MMIOM_CODEC_DECOMPRESS 


MMIOM_CODEC_DECOMPRESS 

This message requests that data be compressed by the CODEC. 

Parameters 

phcodec (PHCODEC)—input 
A pointer to CODEC handle. 
usMsg (USHORT)—input 

Sets to MMIOM_CODEC_DECOMPRESS. 

IParamI (LONG)—input 

A pointer to a MMVTDEODECOMPRESS structure. 
lParam2 (LONG)—input 
This paramter is not used. 

Returns 


rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIOJ3UCCESS 

MMIOJERROR 

MMIOERR_ERROR_IN_FRAME_DATA 

MMIOERR_INVALID_DIM_ALIGN 


Remarks 


None. 
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MMIOM_CODEC_OPEN 

MMIOM_CODEC_OPEN 

This message requests that a CODEC be opened. 

Parameters 

phcodec (PHCODEC)—input/output 
Pointer to CODEC handle. 
usMsg (USHORT)—input 

Set to MMIOM_CODEC_OPEN. 

IParamI (LONG)—input 

Pointer to a CODECOPEN structure. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIOJ3UCCESS 

MMIOJERROR 

Remarks 


None. 
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MMIOM_CODEC_QUERYNAME 


MMIOM_CODEC_QUERYNAME 

This message requests the name of CODEC. 

Parameters 

phcodec (PHCODEC)—input 
A pointer to CODEC handle. 
usMsg (USHORT)—input 

Sets message to MMIOM_CODEC_QUERYNAME. 

IParamI (LONG)—input/output 
A pointer to the name string buffer. 
lParam2 (LONG)—input/output 

A pointer to the name string buffer length in bytes. On output, the actual 
number of bytes read is returned. 

Returns 

rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIO.ERROR 

Remarks 


None. 
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MMIOM_CODEC_QUERYNAMELENGTH 


MMIOM_CODEC_QUERYNAMELENGTH 

This message requests the length of the name for a CODEC. 

Parameters 

phcodec (PHCODEC)—input 
Pointer to CODEC handle. 
usMsg (USHORT)—input 

Set to MMIOM_CODEC_QUERYNAMELENGTH. 
IParamI (LONG)—input/output 

A pointer to the length in bytes of the CODEC name string. 
lParam2 (LONG)—input 
This parameter is not used. 

Returns 

rc (ULONG) 

Returns codes indicating success or type of failure: 

MMIO.SUCCESS 

MMIO_ERROR 

Remarks 


None. 
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DATA STRUCTURES 


BITMAPFILEHEADER2 

This data type is a standard OS/2 data type. 

Fields 

usType (USHORT) 

Specifies the type of resource the file contains. The valid values are: 
BFT_BMAP— Bitmap 
BFTJCON— Icon 
BFT_POINTER— Pointer 
BFT_COLORICON —Color icon 
BFT_COLORPOINTER —Color pointer 
cbSize (ULONG) 

The size of the BITMAPFILEHEADER2 data structure in bytes. 
xHotspot (USHORT) 

The x-coordinate of the hotspot for icons and pointers. This field is ignored 
for bitmaps. 

yHotspot (USHORT) 

The y-coordinate of the hotspot for icons and pointers. This field is ignored 
for bitmaps. 

offbits (ULONG) 

The offset in bytes to the beginning of the bitmap pel data in the file, from 
the start of the definition. 
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BITMAPINFOHEADER2 

This structure contains size, color type, extent, and the palette information for 
an image. This data type is a standard OS/2 data type. 


Fields 


cbFix (ULONG) 

Specifies the size of this header from this field forward, 
cx (ULONG) 

Specifies the width of the bitmap in pels, 
cy (ULONG) 

Specifies the height of the bitmap in pels. 
cPlanes (USHORT) 

Specifies the number of planes. Currently OS/2 PM supports only one. 
cBitCount (USHORT) 

Specifies the number of bits per pel. Valid values are 1, 4, 8, or 24 

ulCompression (ULONG) 

Compression scheme used to store the bitmap. For uncompressed data the 
valid value for the standard presentation format is BCA_UNCOMP = 
OxFFFFOOOO. 

cblmage (ULONG) 

Length of bitmap storage data, in bytes. This field should match the value in 
ulMemSize field of the XDIBHDR__PREFIX structure. 

cxResolution (ULONG) 

Horizontal resolution x-component of the target device that the bitmap is 
intended for, in the units specified the usUnits field. This information, along 
with the y-resolution, enables applications to pick out a bitmap from a 
resource group to best fit the characteristics of the current output device. 

cyResolution (ULONG) 

Vertical resolution y-component of the target device that the bitmap is 
intended for, in the units specified the usUnits field. This information, along 
with the resolution. 
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cclrUsed (ULONG) 

Number of color indexes used. A 0 value (default) means all the colors are 
used. For a nonzero value, only the first cclrUsed-10 entries in the color 
table are accessed. The rest can be omitted. 

For standard formats, with a cBitCount of 1,4, or 8, any indexes beyond the 
value in this field is invalid. For example, a bitmap with 64 colors can use 
the 8-bit count format without having the supply the other 192 entries in 
the color table. For the standard 24-bit count, this field contains the number 
of colors used by the bitmap. 

cclrlmportant (ULONG) 

Number of important color indexes. The first cclrlmportant color entries are 
important. A zero (default) means that all are important. For a 24-bit count 
standard, these colors also are listed in the ulColorEncoding color array. 

This information helps to make palette management more responsive to an 
application’s needs. The important colors are more likely to be assigned to 
the device palette, while others might be mapped to the nearest colors avail¬ 
able. 

usUnits (USHORT) 

Units of measure for the horizontal and vertical resolution. BRU_METRIC, 
or pels per meter, is the default value. 

usReserved (USHORT) 

Reserved for future use and must be set to zero. 

usRecording (USHORT) 

Recording algorithm used. This field must be set to BRA_BOTTOMUP. 
Scan lines will be handled in bottom-to-top order. 

usRendering (USHORT) 

This field is currently not used. Its purpose is for the specification of a half¬ 
toning algorithm. The algorithm is used to record bitmap data that has been 
digitally half-toned. Valid values might include: 

BRH.NOTHALFTONED— Bitmap data is not half-toned. This is the 
default. 

BRH_ERRORDIFFUSION —Error-diffusion or damped error-diffusion 
algorithm. 

BRH_PANDA —Processing algorithm for noncoded document acquisition. 
BRH_SUPERCIRCLE —Super circle algorithm. 



APPENDIX B: Multimedia Input/Output 679 


cSizel (ULONG) 

Size value of field 1. If BRH_ERRORDIFFUSION is specified in the 
usRendering field, this represents the error damping as a percentage in the 
range 0-100%. A value of 100% indicates no damping; a value of 0% indi¬ 
cates that errors are not diffused. 

cSize2 (ULONG) 

Size value of field 2. If BRH_ERRORDIFFUSION is specified in the 
usRendering field, this parameter is ignored. If BRH_PANDA or 
BRH_SUPERCIRCLE is specified, this cSize2 field is the ydimension of 
the pattern used, in pels. 

ulColorEncoding (ULONG) 

A color encoding array. Each element in this array is an RGB2 structure, 
ulldentifier (ULONG) 

Reserved for application use. 


CODECASSOC 

This data structure is used to associate a compressor or decompressor with a 
MMIO handle of an open file. This structure is used on the mmioSet API or 
the MMIOM_SET message. 


Fields 


pCodecOpen (PVOID) 

A pointer to a CODECOPEN structure used by the file format I/O proce¬ 
dure to open the CODEC Proc. If the file, such as playing a file already 
exists, only the pDstHdr field of the CODECOPEN structure is set by the 
application. Other information in CODECOPEN structure will be set by 
the file format I/O procedure. 

pCODECIniFilelnfo (PCODECINIFILEINFO) 

A pointer to the CODECINIFILEINFO structure. This structure contains 
information that identifies a CODEC. 
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CODECINIFILEINFO 

This structure contains information about a CODEC entry in the MMPMM- 
MIO.INI file. Each entry describes a CODEC that can be used by the system. 
Some CODECs may have several entries in the MMPMMMIO.INI file. This 
structure is used on the mmioIniFileCODEC API. 


Fields 


ulStructLen (ULONG) 

This field indicates the length of the CODECINIFILEINFO structure, 
fee (FOURCC) 

The character code that identifies the file format (for example, AVI). 

szDLLName[DLLNAME_SIZE] (CHAR) 

The DLL file name of the CODEC Proc. 
szProcName[PROCNAME_SIZE] (CHAR) 

The entry procedure name of the CODEC Proc. 
ulCompressType (ULONG) 

Specifies the compression type. For example, the TIFF file format has defined 
2 for CCITT G3 modified Huffman run-length encoding, 5 for LZW compres¬ 
sion. 

ulCompressSubType (ULONG) 

Specifies the compression subtype. For example, the TIFF file format has 
defined 6 as the compression type for JPEG, 1 as the compression subtype 
for Lossless Process with Huffman Coding. 

ulMediaType (ULONG) 

Indicates the media type of the CODEC Procedure (for example, image, 
audio, video, or plain data). The following are the currently defined types: 

MMIO_MEDIATYPE_DIGITAL VIDEO 

ulCapsFlags (ULONG) 

Indicates the capabilities supported by the CODEC Proc. The following 
capabilities are defined for video. 
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CODEC_COMPRESS —Can compress. 

CODEC_DECOMPRESS —Can decompress. 

CODEC_WINDOW_CLIPPING— Supports clipping. 

CODEC_PALETTE_TRANS —Supports palette translation. 

CODEC_SELFHEAL —Supports self healing data stream. 

CODEC_SCALE_PEL_HALVED —Supports pel halving of the source 
image. 

CODEC_SCALE_CONTINUOUS —Supports continuous scaling or 
stretching. 

CODEC_MULAPERTURE —Indicates the CODEC Proc supports multi 
aperture algorithm. If this bit is off, fixed aperture is assumed. 

CODEC_4_BIT_COLOR —Indicates the CODEC Proc supports 16 colors. 

CODEC_8_BIT_COLOR —Indicates the CODEC Proc supports 256 colors. 

CODEC_16_BIT__COLOR —Indicates the CODEC Proc supports 65536 
colors. 

CODEC_24_BIT_COLOR —Indicates the CODEC Proc supports 16777216 
colors. 

CODEC_HARDWARE —Indicates that the CODEC Proc is hardware 
assisted and the name of the hardware contained in szHWIDO field. 

CODEC__SYMMETRIC —Indicates the CODEC Proc supports symmetric 
record. 

CODEC_ASYMMETRIC —Indicates the CODEC Proc supports asymmetric 
record. 

CODEC_DIRECTJDISPLAY —Indicates the CODEC Proc can directly 
compress into the video ram. 

CODECJDEFAULT —Indicates that this CODEC entry will be loaded as a 
default when multiple CODEC entries for the same algorithm are installed 
in the initialization file. This allows the application to select the best per¬ 
formed CODEC. 

CODEC_ORIGIN_LOWERLEFT— Indicates the CODEC Proc will decom¬ 
press data to the destination buffer using the lower left as window origin. 
The compressed data lines will be stored in reverse order in the destination 
buffer. Must be set when CODEC_WINDOW_CLIPPING or 
CODECJDIRECT_DISPLY are not set to allow Presentation Manager to 
display data correctly. 
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CODEC_ORIGIN_UPPERLEFT— Indicates the CODEC Proc will decom¬ 
press data to the destination buffer using the upper left as window origin. 
This means that decompressed data lines will be stored in the same order as 
the incoming compressed data lines. 

CODEC_SET_QUALITY —Indicates the CODEC Proc supports the quality 
level setting. Refer to the MMVIDEOOPEN structure for details. 

CODEC_DATA_CONSTRAINT —Indicates the CODEC Proc supports the 
data constraint and interval setting. Refer to the MMVIDEOOPEN struc¬ 
ture for details. 

ulFIags (ULONG) 

Reserved for future use and must be set to zero. 
szHWID[CODEC_HW_NAME_SIZE] (CHAR) 

A null terminated hardware adapter name string associated with CODEC. 

uIMaxSrcBufLen (ULONG) 

Indicates the maximum source buffer length in bytes the CODEC Proc can 
handle. Zero indicates unlimited size. 

ulSyncMethod (ULONG) 

Indicates the synchronization methods supported by the CODEC Proc. The 
following are currently defined for video. 

CODEC_SYNC_METHOD_N0_DR0P_FRAMES —The CODEC will not 
be requested to drop frames. This means that the 
MMIO_DROP_DELTA_FRAME flag will not be set, even if video is 
behind. CODECs with this synchronization method will not maintain audio 
synchronization if insufficient processing resources are available to decom¬ 
press and display data in real time. Factors contributing to this situation 
include computational complexity of the CODEC during decompression, 
hardware capabilities such as processor speed, bus speed, video I/O (memory 
wait state) speed, and other processes running in the system contending for 
processor resources at potentially higher priority levels. Continuity of play¬ 
back of the audio soundtrack is not assured using CODECs with synchro¬ 
nization method zero. 

CODEC_SYNC_METHOD_DROP_FRAMES_IMMEDXATELY —The 
MMIO_DROP_DELTA_FRAME flag will be set whenever video is behind 
by more than a threshold. The CODEC implementation determines the 
appropriate action to take when the MMIO_DROPJDELTA_FRAME flag 
is set. CODECs that are unable to drop individual delta frames within a 
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delta frame sequence may choose to decompress the data but forgo display of 
the decompressed data to refuse processing complexity in an attempt to 
“catch up.” Such an approach should be used only to a certain extent, to 
ensure continuity of the audio soundtrack playback. That is, if the reduction 
in processing complexity is not sufficient to get caught up, and if drop frame 
requests continue to occur on consecutive frames, then the CODEC should 
further reduce its processing complexity by dropping frames completely 
until the next key frame. 

CODEC_SYNCJVlETHOD_DROP_FRAMESJPRECEDING_KEY —The 
MMIO_DROP_DELTA_FRAME flag will be set whenever video is behind 
by more than a threshold, at points in the stream where the time remaining 
to the next key frame is less than or equal to the time interval by which the 
video is behind. In most cases, the effect of this method is that only delta 
frames preceding key frames are dropped. If the video falls behind and no 
key frames are encountered within two seconds in the data stream, delta 
frames will be dropped without regard to key frame proximity. If the video 
falls behind and the data stream contains consecutive key frames, key 
frames will be dropped. 

IReservedI (ULONG) 

Reserved for future use and must be set to zero. 

ulXalignment (ULONG) 

Indicates the top byte alignment of the starting address of the video window. 
This field is valid only when CODECJMULAPERATURE and 
CODEC_DIRECT_DISPLY are set. It is required for the system to place 
the top left corner of the video window on the specified boundary so the 
decompressor can improve performance. For example, 2 means the starting 
video memory address is on the word boundary. If 0 is specified, the 1-byte 
is assumed. 

ulYalignment (ULONG) 

Indicates the top byte alignment of the starting address of the video window, 
This field is valid only when CODECJMULAPERATURE and 
CODEC_DIRECT_DISPLY are set. This information is provided by the 
block oriented decompressor to allow the system to position the top left video 
window corner on a specific scan boundary to avoid dividing it between two 
64KB apertures. The remainder of the 64 is divided by the ulAlignment and 
scale factor (for example, 2 for pel doubling) must be 0. This field is ignored 
when CODEC JSC ALE_C ONTINUOUS is specified. 

ulSpecInfo[CODEC_INFO_SIZE] (ULONG) 

Contains the CODEC-specific information. 
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CODECOPEN 

This structure contains information that is used to open a CODEC. It describes 
the source data format and the destination data format, as well as control and 
CODEC-specific information to indicate the operation of the CODEC. This 
structure is used on the MMIOM_CODEC_OPEN message. 


Fields 


ulFlags (ULONG) 

Contains commands to the CODEC Proc. Flags are the same as ulCapsFlags 
field defined in CODECINIFILEINFO structure. For example, if the flags 
CODEC_8_BIT_COLOR and CODEC_DECOMPRESS are specified, the 
returned instance handle will support decompression into 256 colors. 

pControlHdr (PVOID) 

Contains the control parameters for compression or decompression. The file 
I/O procedure must propagate this control information to the CODEC Proc 
at CODEC initialization. The information is CODEC specific, for example, 
Hufman parameters. If NULL, the default is assumed. 

pSrcHdr (PVOID) 

Contains the source header for video compression or decompression. For 
video, it is CODECVIDEOHEADER. Refer to the CODECVIDEOHEAD- 
ER structure for detailed information. 

pDstHdr (PVOID) 

Contains the destination header for compression or decompression. For 
video, it is CODECVIDEOHEADER. 

Note: Fields not used in the structure must be set to NULL. 

Refer to the CODECVIDEOHEADER structure for detailed information. 

pOtherlnfo (PVOID) 

For video, this points to the MMVIDEOOPEN structure. This field is only 
used if the CODEC has the CODEC_DATA_CONSTRAINT capability 
specified in the ulCapFlags field of CODECINIFILEINFO. 
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CODECVIDEOHEADER 

This structure is the video CODEC header, and it describes the data format of 
either the source video or the destination video. It is used on the 

MMIOM_CODEC_OPEN message. 

Fields 

ulStructLen (ULONG) 

This field indicates the length of the CODECVIDEOHEADER structure, 
cx (ULONG) 

Specifies the width of the bit map, in pels, 
cy (ULONG) 

Specifies the height of the bitmap, in pels. 
cPlanes (USHORT) 

Specifies the number of planes. The value is normally set to 1. 
cBitCount (USHORT) 

Specifies the number of bits pe pel. Valid values are 1, 4, 8, 16 and 24. 
ulColorEncoding (ULONG) 

Color encoding. If zero is specified, the default is assumed. 
MMXO_RGB_5_6_5 —Each pel is RGB_5_6_5 data type. 

MMIO_RGB_24 —Each pel is RGB_24 data type. 

MMIO_YUV_4_l_l —Each pel is YUV_4_1_1 data type. 

MMIO_YUV_24 —Each pel is YUV_24 data type. 

MMIO_COMPRESSED —The data is compressed. 

MMIO_PALETTIZED —The data is palettized. Number of bits per pel 
specified in cBitCount. 
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genpal (GENPAL) 

For the pScrHdr field of CODECOPEN, this field contains the video stream 
palette. For pDstHdr field of CODECOPEN, this field contains the destina¬ 
tion color space (for example, the physical palette if the 
CODEC_DIRECT_JDISPLAY capability flag is set). The ulStartlndex field 
of GENPAL structure is always NULL. prgb2Entries field of GENPAL is 
NULL when the number of colors exceeds 256. 


FOURCC 


FOURCC 

This data type contains a four-character code that is used as an identifier for 
I/O procedures and CODECs. 


GENPAL 


This structure is a generic palette, and it defines a color palette of up to 256 
entries. This structure is used as part of the CODECVIDEOHEADER 
structure. 


Fields 


ulStartlndex (ULONG) 
Starting RGB index. 
ulNumColors (ULONG) 
Number of following entries. 
prgb2Entries (PRGB2) 

256 RGB entries. 


HCODEC 

A CODEC instance handle returned by the MMIOM__CODEC_OPEN mes¬ 
sage. It is used on the other CODEC messages to identify the instance. 
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HMMCF 


A RIFF compound file instance handle returned by the mmioCFOpen API. It 
is used on the other compound file APIs to identify the instance. 


HMMIO 


An MMIO data object instance handle returned by the mmioOpen API. It is 
used on the other data object APIs and messages to identify the instance. 


MIDIHEADER 

This structure is a MIDI sub-header, and it is usually contained within the 
MIDIHEADER structure. It is part of the standard presentation format for 
MIDI data and is returned on an mmioGetHeader API. Additionally MIDI¬ 
HEADER is used on the mmioSetHeader API when the HMMIO refers to an 
open MIDI file. 


Fields 


chHeaderChunk[4] (CHAR) 

The characters used to identify the chunk type. They will always be M, C, H, 
and D. 

ulHeaderLength (ULONG) 

Length of the chunk as previously described. Under most scenarios the 
value would be 6. 

usFormat (USHORT) 

The format of the file. The currently accepted values are 0 and 1. All 0 for¬ 
mat files have one track of information. Format 1 files can have more than 
one track of information. 

usNumTracks (USHORT) 

The number of tracks in the file. For format 0 this would be 1 track. 
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usDivision (USHORT) 

The time format of the file. If the high order bit is 0, the time format is ticks 
per Quarter note. Otherwise the time format is SMPTE, with the lower 8 
bits representing ticks per frame and bits 8-14 representing the negative 
SMPTE format. If you need more information on the time format of the file, 
see The Standard MIDI Files published by the International MIDI 
Association. 

vpAdditionallnformation (PVOID) 

A pointer to additional MIDI information. 


MMAUDIOHEADER 

This structure is the audio header, and it describes attributes of an open audio 
file. It is the standard presentation format for audio data and is returned on an 
mmioGetHeader API. It is used on the mmioSetHeader API when the 
HMMIO refers to an open audio file, or to an open movie file when the active 
track for this file is set to a audio track. 


Fields 


ulHeaderLength (ULONG) 

Length of this header, in bytes. 
ulContentType (ULONG) 

Audio content type. Acceptable values for this field are as follows: 
MMIO_MIDI_UNKNOWN —Unknown MIDI content. 
MMIO_MIDI_VOICE —Limited range. 

MMIO_MIDI_MUSIC —FM radio or equivalent. 

MMIO_MIDI_HIFI —High quality recording. 
ulMediaType (ULONG) 

The type of multimedia data in the file. This will be determined by MMIO 
and returned to the application. The currently defined value is: 

MMIO_MEDIATYPE_AUDIO 
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mmXWAVHeader (MMXWAV.HEADER) 

Contains specific information about the digital audio content including the 
format of the data representation for the data that it is associated. 


MMCFINFO 

This structure contains information about a RIFF compound file. There are 
three optional fields that may follow this structure and they are variable 
length arrays of information. This structure is returned on the 
mmioCFGetlnfo API and used on the mmioCFSetlnfo API. 


Fields 


ulHeaderSize (ULONG) 

The size of the compound table of contents (CTOC) header, including the 
variable-length arrays aulExHdrFldUsage, aulExEntFldUsage , and 
aulExHdrField. 

ulEntriesTotal (ULONG) 

The total number of CTOC table entries, including unused entries and 
entries corresponding to deleted compound-file elements. 

ulEntriesDeleted (ULONG) 

The number of CTOC table entries that refer to deleted CGRP elements. 
ulEntriesUnused (ULONG) 

Number of unused CTOC entries. 
ulBytesTotal (ULONG) 

The combined size of all elements in the CGRP, including deleted elements. 
ulBytesDeleted (ULONG) 

The combined size of all deleted elements in the CGRP. 
ulHeaderFlags (ULONG) 

Flags that give information about the entire file. 

CTOC_HFJ3EQUENTIAL —Indicates that the valid entries in the CTOC 
table (that is, the entries that are neither deleted nor unused) are in the 
same order as the corresponding elements in the CGRP. If this bit is not set, 
the CTOC table entries might be in an arbitrary order. 
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CTOC_HF_MEDSUBTYPE —If this flag is set (bit value 1), then the 
ulMedUsage field of each CTOC table entry (MMCTOCENTRY structure) 
contains a four-character code that is a media element sub-type. If the flag is 
not set (bit value is 0), the ulMedUsage field is simply 32-bits of information 
that is interpreted as defined by the form type. 

usEntrySize (USHORT) 

The size of each CTOC table entry. Each entry is the same size. 
usNameSize (USHORT) 

The size of the pszElementName field of each CTOC table entry, including 
the terminating NULL. Each pszElementName field must be padded with 
NULL to this length, and there must be at least one NULL. 

usExHdrFields (USHORT) 

The number of extra header fields; that is, the number of items in the arrays 
aulExHdrFldUsage and aulExHdrField. 

usExEntFields (USHORT) 

The number of extra entry fields; that is, the number of items in the arrays 
aulExEntFldUsage and aulExEntField, of each CTOC table entry. 

Optional Fields 

(*aulExHdrFldUsage) [] (ULONG) 

(*aulExtEntFldUsage)[] (ULONG) 

(*aulExHdrField) [] (ULONG) 


MMCKINFO 

This structure contains information about a chunk in a RIFF file. It is used on 
the mmioCreateChunk, mmioDescend, and mmioAscend API. 


Fields 


ckid (FOURCC) 

Chunk ID (FOURCC). 
ckSize (ULONG) 

The size of the data portion of the chunk. It does not include the four-byte 
chunk ID, the four-byte chunk size, or the pad byte (if present). 
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fccType (FOURCC) 

The form type (for RIFF chunks) or list type (for LIST types). 
ulDataOffset (ULONG) 

The file offset of the beginning of the data portion on the chunk (8 bytes 
from the beginning of the chunk header). 

ulFlags (ULONG) 

MMIO_DIRTY indicates the chunk was created by mmioCreateChunk API. 


MMCOMPRESS 

This structure contains information used on an MMIOM_COMPRESS and 
MMIOM_CODEC_COMPRESS message call to a CODEC. 


Fields 

ulStructLen (ULONG) 

Indicates the length of entire structure. 
ulFlags (ULONG) 

Some flags are set to instruct the I/O or CODEC procedure to act. Some 
flags are status returned from the I/O or CODEC procedure. 

MMIO_IS_KEY_FRAME —This bit is set by the application to instruct the 
I/O procedure to compress the pSrcBuf field into a key or reference frame. If 
the bit is not set, a delta frame is compressed. 

MMIO_IS_P ALETTE —A video palette is provided. Set by the application. 

ulSrcBufLen (ULONG) 

The length in bytes of the buffer pointed to by pSrcBuf field. On return, the 
length is updated to reflect the remaining number of compressed data bytes 
that have been processed. 

pSrcBuf (PVOID) 

A pointer to the source uncompressed data. 

ulDstBufLen (ULONG) 

The length in bytes of the buffer pointed to by pDstBuf field. On return, the 
length is updated to reflect the compressed data pointed to by pDstBuf. 
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pDstBuf (PVOID) 

A pointer to the destination buffer that will contain compressed data. 

pRunTimelnfo (PVOID) 

Control information pointer to MMVIDEOCOMPRESS. 


MMCTOCENTRY 

This structure contains information about an entry in the compound table of 
contents (CTOC) of a RIFF compound file. There are two optional fields, a vari¬ 
able-length name field and ULONG array, that may follow this structure. This 
structure is used on the mmioCFAddEntry , mmioCFChangeEntry, 
mmioCFDeleteEntry, and mmioCFFindEntry API. 


Fields 


ulOffset (ULONG) 

The offset of the compound-file element within the compound-file resource- 
group (CGRP) chunk. This offset is measured from the beginning of the data 
portion of the chunk. For example, if ulOffset is 1000, and the chunk ID of 
the CGRP chunk is at offset 500, then the element is at offset 1508 (the 8 is 
because the chunk ID and chunk size occupy 4 bytes each). 

ulSize (ULONG) 

The size that the element occupies in the CGRP chunk. 
ulMedType (ULONG) 

The four-character code of the media element type of the compound-file 
entry that the CTOC entry refers to. This field can be 0 if the compound-file 
entry is not to be interpreted as a stand-alone file. If the compound-file entry 
is a RIFF form, then the media element type is the same as the RIFF form 
type. 

ulMedUsage (ULONG) 

If the flag, CTOC_HF_MEDSUBTYPE is present in the ulHeaderFlags 
field of the CTOC header (MMCFINFO), then the ulMedUsage field of each 
CTOC table entry (MMCTOCENTRY) contains a four-character code that 
is a media element subtype. If the flag is not set, the ulMedUsage field is 
simply 32-bits of information, which is defined by the form type. 
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ulCompressTech (ULONG) 

The compression technique used to compress the compound-file element. If 
this value is 0, the element is not compressed. 

ulUncompressBytes (ULONG) 

The number of bytes that the compound-file element will occupy in memory 
after it has been decompressed by the decompression code associated with 
compression technique, ulCompressTech field of MMCTOCENTRY. If the 
ulCompressTech field is 0, the compound-file element is not compressed, and 
ulUncompressBytes field of MMCTOCENTRY equals ulSize field of MCTO- 
CENTRY, the file size of the compound-file element. 


MMDECOMPRESS 

This structure contains information used on an MMIOM_DECOMPRESS and 

MMIOM_CODEC_DECOMPRESS message call to a CODEC. 


Fields 


ulStructLen (ULONG) 

Indicates the length of entire structure. 
ulFlags (ULONG) 

Some flags are set to instruct the I/O or CODEC procedure to act. Others are 
status, returned from the I/O or CODEC procedure. 

MMXO_DROP_DELTA_FRAME —Tells the I/O or CODEC procedure to 
drop the delta frame if the pSrcBuf field contains a delta frame. On return, 
the bit is reset if the delta frame is dropped. 

MMIO_IS_KEY_FRAME —This bit is set by the I/O or CODEC procedure 
when the data contained in the pSrcBuf field is a key reference frame. 

MMXO_IS_PALETTE —A video palette is found. Set by the I/O procedure. 

MMIO_PALETTE_CHANGE —The physical palette has been changed in 
genpalPhysical field of MMVIDEODECOMPRESS structure. It is set by 
the application. 

MMXO_ORIGIN_LOWERLEFT —Tells the I/O or CODEC procedure to 
decompress data to the destination buffer using the lowerleft as window ori¬ 
gin. This means the decompressed data line will be stored in reverse order 
in the destination buffer. 
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MMIO_ORIGIN_UPPERLEFT —Tells the I/O or CODEC procedure to 
decompress data to the destination buffer using the upper-left as window 
origin.This means the decompressed data lines will be stored in the same 
order as the incoming compressed data lines. 

MMIO_RECTL_CHANGE —The movie rectangle has been changed. Valid 
rectangles are specified in prectl field and ulRectlCount field of 

MMVIDEODECOMPRESS structure. 

ulSrcBufLen (ULONG) 

The length in bytes of the buffer pointed to by pSrcBuf field. On return, the 
length is updated to reflect the remaining number of compressed data bytes 
that need to be processed. Zero must be returned when all bytes are decom¬ 
pressed. 

pSrcBuf (PVOID) 

A pointer to the source compressed data. On return the pointer is adjusted 
to point to the data not yet compressed. The NULL must be returned when 
all data in pSrcBuf field is decompressed. 

ulDstBufLen (ULONG) 

The length in bytes of the buffer pointed to by pDstBuf field. On return, the 
length is updated to reflect the compressed data pointed to by pDstBuf field. 

pDstBuf (PVOID) 

A pointer to the destination uncompressed data. 

pRunTimelnfo (PVOID) 

Pointer to MMVIDEODECOMPRESS. Contains the CODEC runtime 
information. 


MMEXTENDINFO 

This structure contains information used on an mmioSet API call to a digital 
video I/O procedure. It contains information used to associate a CODEC with 
an open file or to query information about CODECs already loaded. This struc¬ 
ture also provides a way of setting attributes used in reading and writing from 
a digital video movie file. 
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Fields 


ulStructLen (ULONG) 

Indicates the length of entire structure. 
ulBufSize (ULONG) 

Indicates the length of buffer in bytes to hold the entire information when 

the MMIO_UERY_EXTENDINFO_ALL flag is set. 

ulFlags (ULONG) 

Specifies the following flags: 

MMIO_TRACK—If set, all MMIO operations will be performed on the 
active track specified in ulTrackID field. 

MMIOJREVERSEJREAD—If set, all MMIO operations will be performed 
in reverse. 

MMIO_SCAN_READ—If set, all MMIO operations will be performed in 
scan mode, meaning only key video frames are processed. 

MMIO_NORMAL_READ—If set, all MMIO operations will be performed 
in Normal mode, which processes all frames. 

MMIO_CODEC_ASSOC—If set, the pCODECAssoc field and 
ulNumCODECs field are used for setting the active CODECs or returning 
the CODEC information. 

ulTrackID (ULONG) 

The active track identifier set to the file. If MMIO_RESETTRACKS is 
specified, all MMIO operations are performed on the file basis. 

ulNumCODECs (ULONG) 

Specifies the number of entries in the buffer pointed to by the CODECAS- 
SOC structure. 

pCODECAssoc (ULONG) 

Pointer to the CODECASSOC structure. 
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MMFORMATINFO 

This structure describes some of the characteristics of an I/O procedure and the 
type of data that it can process. It is used on the mmioGetFormatName, 
mmioGetFormats , and mmioQueryFormat Count API. 


Fields 


ulStructLen (ULONG) 

Indicates the length of the entire structure, allowing applications to detect 
changes in future versions. 

fccIOProc (FOURCC) 

The four-character code that uniquely identifies the I/O procedure that is 
responsible for processing this file format. 

ulIOProcType (ULONG) 

Specifies the type of I/O procedure. These include: 

MMIO_IOPRO C_STORAGE S Y STEM 

MMIO_IOPROC_FILEFORMAT 

MMIO_IOPROC_DATAFORMAT 

ulMediaType (ULONG) 

The type of multimedia data in the file. This will be determined by MMIO 
and returned to the application. The currently defined values are: 

MMIO_MEDIATYPE_AUDIO —Audio media 

MMIO_MEDIATYPE_IMAGE —Image media 

MMIO_MEDIATYPE_DIGITALVIDEO —Digital video media 

MMIO_MEDIATYPE_MIDI —MIDI media 

MMIO_MEDIATYPE_MOVIE —Contains digital video and audio data 

MMIO_MEDIATYPE_ANIMATION —Animation media 

MMIO_MEDIATYPE_COMPOUND— Compound media 

MMIO_MEDIATYPE_OTHER —Known media type, but not currently 
defined by MMPM/2 toolkit 

MMIO_MEDIATYPE_UNKNOWN— Unknown media 
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ulFlags (ULONG) 

These flags represent capabilities of the I/O procedure. These flags are set 
only by the I/O procedure. Each flag represents one bit. A value of 1 indi¬ 
cates that capability is supported. The calling routine should check these 
flags to ensure the I/O procedure can accommodate the request. 

MMIO_C ANRE ADTRAN SLATED 

MMIO.CANREADUNTRANSLATED 

MMIO.CANREADWRITETRANSLATED 

MMIO_CANREADWRITEUNTRANSLATED 

MMIO_C ANWRITETRAN SLATED 

MMIO.CANWRITEUNTRANSLATED 

MMIO.CANSEEKTRANSLATED 

MMIO_CANSEEKUNTRANSLATED 

MMIO.CANINSERTTRANSLATED 

MMIO_C ANIN SERTUNTRAN SLATED 

MMIO_CANSAVETRANSLATED 

MMIO.CANSAVEUNTRANSLATED 

MMIO.CANMULTITRACKREADTRANSLATED 

MMIO_C ANMULTITRACKRE ADUNTRAN SLATED 

MMIO_C ANMULTITRACKWRITETRAN SLATED 

MMI_CANMULTITRACKWRITEUNTRANSLATED 

MMIO.CANTRACKSEEKTRANSLATED 

MMIO.CANTRACKSEEKUNTRANSLATED 

MMIO_CANTRACKREADTRANSLATED 

MMIO.CANTRACKREADUNTRANSLATED 

MMIO.CANTRACKWRITETRANSLATED 

MMIO.CANTRACKWRITEUNTRANSLATED 

szDefaultFormatExt[sizeof(FOURCC)+l] (CHAR) 

A 4-character, NULL-terminated string containing the file name extension 
normally associated with this file format. This allows applications creating 
media files to use the most appropriate naming conventions. 

ulCodePage (ULONG) 

The codepage and country code of the format name string for this I/O 
procedure. 
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As described for RIFF compound-files in the IBM-Microsoft Joint 
Specification, the lower-order word contains either: 

• Zero (0): Use standard codepage. 

• Codepage: Specific codepage to be used. 

The high-order word contains either: 

• Zero (0): Ignore this field. 

• Country code: Specific country code. 
ulLanguage (ULONG) 

Provides the language and dialect codes of the format name string for this 
I/O procedure. 

As described for RIFF compound-files in the IBM-Microsoft Joint 
Specification, the low-order word contains either: 

• Zero (0): Ignore this field 

• Language: Specific language to be used 
The high-order word contains either: 

• Zero (0): Ignore this field 

• Reserved: 
lNameLength (LONG) 

Length of format identifier string, not including the NULL-terminating 
character. 


MMIMAGEHEADER 

This structure is the image header, and it describes attributes of an open 
image file. It is the standard presentation format for image data and is 
returned on an mmioGetHeader API. It is used on the mmioSetHeader API 
when the HMMIO refers to an open image file. 


Fields 


ulHeaderLength (ULONG) 

The length of this header in bytes. 
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ulContentType (ULONG) 

The image content type. The acceptable values for this field are as follows: 
MMIO_IMAGE_UNKNOWN —Unknown image content. 
MMIO_IMAGE_DRAWING— Simple drawing. 

MMIO_IMAGE_GRAPH —Graphs and cartoons. 
MMIO_IMAGE_PHOTO —Varying color and shades. 
uIMediaType (ULONG) 

The type of multimedia data in the file. This will be determined by MMIO 
and returned to the application. The currently defined value is: 

MMIO_MEDIATYPE_IMAGE 

mmXDIBHeader (MMXDIBHEADER) 

Extension of OS/2 2.0 PM compatible header. 

bmicolor s [MAX_PALETTE] (RGB2) 

PM compatible palette. 256 entries. 


MMINIFILEINFO 

This structure contains information about a I/O procedure entry in the MMP- 
MMMIO.INI file. Each entry describes an I/O procedure that can be used by 
the system. Each I/O procedure has one entry in the MMPMMMIO.INI file. 
This structure is used on the mmioIniFileHandler API. 


Fields 


fccIOProc (FOURCC) 

The four-character code that identifies the file’s I/O procedure. 

szDLLName[DLLNAME_SIZE] (CHAR) 

The DLL name of the I/O procedure. 
szProcName[PRONAME_SIZE] (CHAR) 

The procedure entry point of the DLL. 
ulFlags (ULONG) 


Reserved. 
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ulExtendLen (ULONG) 

Length of extended fields. 
ulMediaType (ULONG) 

Media type. 

ulIOProcType (ULONG) 

The type of I/O procedure. 

szDefExt[sizeof(MAX_EXTENSION_NAME)] (CHAR) 
Default file extension. 


MMIO_EDIT_PARMS 

This structure contains information for performing edit operations on a file. It 
is used on the MMIOM_CLEAR, MMIOM.COPY, MMIOM.CUT, and 
MMIOM_PASTE messages. 


Fields 


ulStructLen (ULONG) 

The total length of this structure in bytes. The length includes the four bytes 
for this field. 

hwndWindow (ULONG) 

The window handle associated with the current editing operations. This 
handle is used in clipboard related PM calls, such as 

WinSetClipbrdOivner . 

ulStartTime (ULONG) 

The starting time for the operation, expressed in microseconds. The I/O pro¬ 
cedure uses this time to calculate the first element (movie frame, audio byte, 
and so on) to be included in the editing operation or the position for an 
insert. 

ulDuration (ULONG) 

The length of time to be included in the editing operation. 

The I/O procedure uses the ulStartTime and ulDuration fields to calculate 
the last element to be included in the editing operation. 

This parameter is inclusive. If the duration falls in any portion of time occu¬ 
pied by an element, the entire element will be included in the operation. 
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ulCurrentFilePosition (ULONG) 

The current position of the file in microseconds, as viewed by the MCD, at 
the time the editing operation is processed. 

This field is used by the I/O procedure to calculate the starting element for 
the editing operation when the FROM parameter is omitted from the Media 
Control Interface message. 

uINewFilePosition (ULONG) 

The new file position in microseconds. The I/O procedure returns the new 
file position to be set by the MCD, by way of a seek, so that the media is cor¬ 
rectly positioned. The Media Control Interface editing messages define the 
correct new media position. 

ulNewFileLength (ULONG) 

The new length of the file in microseconds after the editing operation is per¬ 
formed. 

The MCD must update any private data structures, such as copies of the file 
header, to reflect this new media length. 

pBuffer (PVOID) 

This field is set from the pBuff field of the MCI_EDIT_PARMS structure if 
MCI_TO_BUFFER flag is specified; this field is NULL if the 
MCI_TOJBUFFER flag is not specified. 

ulBufferLength (ULONG) 

This field is the length of pBuffer and is set from the ulBufLen field of the 
MCIJEDIT_PARMS structure. 

pHeader (PVOID) 

This field is set from the pHeader field from the MCI_EDIT_PARMS 
structure. 
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MMIOINFO 

This structure contains the current state information of an open file. It is 
returned on the mmioGetlnfo API and used on the mmioSetlnfo API. 


Fields 


ulFlags (ULONG) 

Access Mode 

The access mode of the file, equal to one of the following values: 

MMIO_READ —The file was opened only for reading. 

MMIO_WRITE —The file was opened only for writing. 

MMIO_READWRITE —The file was opened for both reading and 
writing. 

File Sharing Mode 

The file sharing mode of the file, equal to one of the following values: 

MMIO_COMPAT —The file was opened with compatibility mode, allow¬ 
ing any process on a given system to open the file any number of times. 

MMIOJEXCLUSIVE —The file was opened with exclusive mode, denying 
other processes both read and write access to the file. 

MMIO_DENYWRITE —Other processes are denied write access to the 
file. 

MMIO_DENYNONE —Other processes are not denied read or write 
access to the file. 

Other Modes 

Other modes of the file, equal to one or more of the following values: 

MMIOjCREATE—mmioOpen API was directed to create the file, or to 
truncate it to 0 length if it already existed. 

MMIO_ALLOCBUF —The file’s I/O buffer was allocated by mmioOpen 
or mmioSetBuffer. 

MMIO_BUFSHARED —Requests that if MMIO allocates the buffer, it 
does so from shared memory. 

MMIOJVERTBAR —Requests that the vertical bar symbol ( I ) be used as 
a file separator character rather than the plus sign (+). 
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MMIO_DELETE —Directs the mmioOpen API to delete the file. 

MMIO_APPEND —Directs the mmioOpen API to allow appending to 
the end of the file. 

MMIO_DIRTY —Forces a write operation on an mmioAdvance API for 
low-level I/O. 

MMIOJNOIDENTIFY —Directs the mmioOpen API not to attempt an 
automatic identification file. 

fccIOProc (FOURCC) 

The four-character code that identifies the file’s I/O procedure. If the I/O 
procedure is not an installed one, this field will be NULL. Refer to the 
mmioOpen API, for a list of the predefined I/O procedures identifiers. 

plOProc (PMMIOPROC) 

The address of the file’s I/O procedure. 

uIErrorRet (ULONG) 

Extended error return code. 

cchBuffer (LONG) 

The size of the file’s I/O buffer (in bytes), or 0 if the file either does not have 
an I/O buffer or has a 0-byte buffer. 

pchBuffer (PCHAR) 

The address of the file’s I/O buffer. If this field is NULL, the file is not 
buffered. 

pchNext (PCHAR) 

Points to the next byte in the I/O buffer to be read or written to. Points to 
pchEndRead if no more bytes can be read without calling mmioAdvance or 
mmioRead. Points to pchEndWrite if no more bytes can be written without 
calling mmioAdvance or mmioWrite. 

pchEndRead (PCHAR) 

The last byte in the buffer from which a file can read. 

pchEndWrite (PCHAR) 

The last byte in the buffer to which a file can write. 

lBufOffset (LONG) 

Reserved for use by the MMIO APIs internally. 
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IDiskOffset (LONG) 


The file offset to which the next mmioRead or mmioWrite API, or 
MMIOM_READ or MMIOM_WRITE message (sent to the file’s I/O proce¬ 
dure) will read or write. Reserved for use by the MMIO APIs internally. 

aulInfo[4] (ULONG) 

State information that is maintained by the I/O procedure. Certain I/O pro¬ 
cedures also use these field, to transfer information from the caller to the 
I/O procedure when the file is opened. Refer to the mmioOpen API. 

lLogicalFilePos (LONG) 

Actual logical-file position, whether buffered or not. 

ulTransIate (ULONG) 

This field is the translation flag field and it has the following possible 
values: 

MMIO_NOTRANSLATE —Neither the Header nor Data portion of the 
file is translated into the defined standard presentation format for the 
specified media type. 

MMIO_TRANSLATEDATA —The Data portion of the file is translated 
into the defined standard presentation format for the specified media 
type. 

MMIO__TRANSLATEHEADER —The Header portion of the file is trans¬ 
lated into the defined standard presentation format for the specified 
media type. 

fccChildlOProc (FOURCC) 

FOURCC structure of the child I/O procedure to be used. In the current 
implementation, this is the storage system I/O procedure. 

pExtralnfoStruct (PVOID) 

Pointer to a structure of related data to be used by the I/O procedure, 
hmmio (HMMIO) 

The MMIO handle to the open file. I/O procedure can use this handle in calls 
to MMIO APIs. 
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MM 10_STATU S_PA RMS 

This structure contains information used on an MMIOM_STATUS message. 


Fields 


hwndWindow (HWND) 

This filed is required if a specific window handle is required to process a sta¬ 
tus request. If this parameter is omitted and a window handle is needed, the 
I/O procedure will use HWND_DESKTOP. 

ulReturn (ULONG) 

Contains the status information upon return, 
ulltem (ULONG) 

The status item to query. 
ulValue (ULONG) 

The status value to extend the status structure. 
ulType (ULONG) 

An MCI_FORMAT flag is returned here, when required, to specify the for¬ 
mat of the value returned in ulReturn; for example, the time format when a 
time value is returned. 


MMIO_WINMSG 

This structure contains information used on an MMIOM__WINMSG message. 
The fields of this structure correspond to the parameters of the WinSendMsg 
and WinPostMsg APIs. 


Fields 


hwndWindow (HWND) 

The handle for the window associated with the window procedure that is 
sending the MMIOM_WINMSG message. 

usMessage (USHORT) 

The Presentation Manager message number. 
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pParml (PVOID) 

The first PM message parameter. 
pParm2 (PVOID) 

The second PM message parameter. 


MMMIDIHEADER 

This structure is the MIDI header, and it describes attributes of an open MIDI 
file. It is the standard presentation format for MIDI data and is returned on an 
mmioGetHeader API. It is used on the mmioSetHeader API when the 
HMMIO refers to an open MIDI file. 


Fields 


ulHeaderLength (ULONG) 

Length of this header, in bytes. 
ulContentType (ULONG) 

This field contains the type of MIDI content and it has the following possible 
values: 

MMIO_MIDI_UNKNOWN— Unknown MIDI content. 
MMIO_MIDI_VOICE —Limited range. 

MMIOJMIDI_MUSIC —FM radio or equivalent. 

MMIO_MIDI_HIFI —High quality recording. 
ulMediaType (ULONG) 

The type of multimedia data in the file. This will be determined by MMIO 
and returned to the application, the currently defined value is: 

MMIO_MEDIATYPE_MIDI 

midiheader (MIDIHEADER) 

A sub-structure containing additional MIDI information. 
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MMMOVIEHEADER 

This structure is the movie (motion video) header and it describes attributes of 
an open movie file. It is the standard presentation format for movie data and is 
returned on an mmioGetHeader API and is used on the mmioSetHeader 
API when the HMMIO refers to an open movie file and the active track for this 
file is set to MMIO_RESETTRACKS. 


Fields 


ulStructLen (ULONG) 

Indicates the length of entire structure. 
uIContentType (ULONG) 

Indicates the movie content type. 
ulMediaType (ULONG) 

The field contains the movie media type (MMIO_MEDIATYPE_MOVIE). 

ulMovieCapsFlags (ULONG) 

Defines the following capabilities: 

MOVTE_HAS_VIDEO —The movie contains video. 

MOVIE_HAS_AUDIO —The movie contains audio. 

MOVIE_CAN_SEEK —The movie can seek. 

MOVIE_CAN_SCAN —The movie can fast scan. 

MOVIE_HAS_COPYRIGHT —The movie contains copyrighted data. 

MOVIE_WAS_CAPTUREFILE —The movie is a specially allocated file 
used for capturing real-time video. Applications should warn the user 
before writing over a file with this flag set because the user probably 
defragmented this file. 

uIMaxBytesPerSec (ULONG) 

Maximum transfer rate. 

uIPaddingGranularity (ULONG) 

Pad to a multiple of this value. 
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ulSuggestedBufferSize (ULONG) 

Suggested buffer size in bytes for reading the file. 
ulStart (ULONG) 

Delay time indicating beginning or starting time of movie. Units defined by 
ulRate and ulScale. These are normally zero, but delay time can be specified 
for a stream that does not start concurrently with the movie file. 

ulLength (ULONG) 

The length of the movie file. 

ulNextTrackID (ULONG) 

Next available track identifier to add. 

ulNumEntries (ULONG) 

The number of track entries in pmmTracklnfoList. 

pmmTracklnfoList (PMMTRACKINFO) 

A pointer to a track information list. Refer to the MMTRACKINFO data 
structure. 

pszMovieTitle (PSZ) 

A pointer to ASCIIZ movie title string. 
ulCountry (ULONG) 

The country code associated with the movie. Unknown if zero. 
ulCodePage (ULONG) 

The country code page associated with the movie. Unknown if zero. 
ulAvgBytesPerSec (ULONG) 

The average transfer rate. 
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MMMULTITRACKREAD 

This structure contains information used on an MMIOM_MULTITRACK- 
READ message. 

Fields 

ulLength (ULONG) 

Indicates the amount of data in bytes to be read into pBuffer. I/O should be 
performed on this buffer length. The actual buffer length can be bigger and 
is given in ulBufferLength . Video frames can span pBuffer + ulLength as 
long as the frame is less than ulBufferLength in size. 

pBuffer (PVOID) 

A pointer to the buffer into which the contiguous file data will be read. 
ulFlags (ULONG) 

MMIOM_MULTITRACKREAD —Input flag values: 

MULTITRACKREADJEXTENDED —Indicates the new extended multi¬ 
track read structures passed from caller instead of the previous multi¬ 
track read structure. 

MMIOM_MULTITRACKREAD —Output flag values. 

MULTITRACKREAD_NOTDONE —The record table entries of a track 
are insufficient to hold all the data of the track in pBuffer. To continuous¬ 
ly get the record entries, the application must re-issue MMIOM__MULTI- 
TRACKREAD with the same pBuffer. 

MULTITRACKREAD_EOF —End of file is reached. This is useful when 
the number of bytes read do not match the length of the buffer because a 
record spans into the next buffer. 

ulNumTracks (ULONG) 

Specifies the number of TRACKMAP entries in pTrackMapList. 

pTrackMapList (PTRACKMAP) 

A pointer to a track-to-record list table. Refer to the TRACKMAP data 
structure. 

ulBufferLength (ULONG) 

Actual length of read buffer {pBuffer). 
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ulReserved (ULONG) 


Reserved for future use and must be set to zero. 


MMULTITRACKWRITE 

This structure contains information used in an MMIOMJMULTITRACK 
WRITE message. 


Fields 


ulNumTracks (ULONG) 

Specifies the number of TRACKMAP entries in pTrackMapList. On output, 
it returns the actual number of entries written. 

pTrackMapList (PTRACKMAP) 

A pointer to a track-to-record list table. Refer to the TRACKMAP data 
structure. 

ulFlags (ULONG) 

MULTITRACKWRITEJVtERGE —This flag is an input value. It tells the 
I/O procedure to attempt to interleave the data on the write. The default 
(without this flag set) is to write all records for each track, then write all 
records of the next track, and so on. 

ulReserved (ULONG) 

Reserved for future use and must be set to zero. 


MMTRACKINFO 

This structure is a movie sub-header and is considered part of a movie header. 
The MMMOVIEHEADER pmmtrackinfo field points to an array of these 
structures. The ulNumTracks field of that structure contains the number of 
entries in this array. It is part of the standard presentation format for movie 
data and is returned on an mmioGetHeader API and is used on the 
mmioSetHeader API when the HMMIO refers to an open movie file. 

Fields 


ulTrackID (ULONG) 
Track identifier. 
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ulMediaType (ULONG) 

The following media types are valid: 

MMIO_MEDIATYPE_IMAGE 

MMIO_MEDIATYPE_AUDIO 

MMIO_MEDIATYPE_MIDI 

MMIO_MEDIATYPE_DIGITALVIDEO 

MMIO_MEDIATYPE_ANIMATION 

MMIO_MEDIATYPE_COMPOUND 

MMIO_MEDIATYPE_MOVIE 

MMIO_MEDIATYPE_OTHER —Known media type not yet supported. 
MMIO_MEDIATYPE_UNKNOWN —Unknown media type. 
ulCountry (ULONG) 

Country code associated with the track. Unknown if zero. 

ulCodePage (ULONG) 

Country codepage number associated with the track. Unknown if zero. 
ulReserved (ULONG) 

Reserved for future use and must be set to zero. 
ulReserved2 (ULONG) 

Reserved for future use and must be set to zero. 


MMVIDEOCOMPRESS 

This structure contains information used on an MMIOM_COMPRESS and 
MMIOM_CODEC_COMPRESS message call to a CODEC. It defines 
CODEC-specific control information. The pRunTimelnfo field of the MMCOM- 
PRESS structure points to this structure. 


Fields 


ulStructLen (ULONG) 

Indicates the length of entire structure. 
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genpalVideo (GENPAL) 

Contains the video stream palette. 

pControlHdr (PVOID) 

Contains control parameters for compression. The information is CODEC- 
specific, that is, HUFFMAN parameters. If NULL, default assumed. 


MMVIDEODECOMPRESS 

This structure contains information used on an MMIOM_DECOMPRESS and 
MMXOM_CODEC_DECOMPRESS message call to a CODEC. It defines 
CODEC-specific control information. The pRunTimelnfo field of the MMDE- 
COMPRESS structure points to this structure. 

Fields 

ulStructLen (ULONG) 

Indicates the length of entire structure. 
ulRectCount (ULONG) 

Valid rectangle count for clipping, 
prectl (PRECTL1) 

Valid rectangle array for clipping. 
ulSkipLength (ULONG) 

Indicates the skipped line length after each line is decompressed. 
ulDecodeLines (ULONG) 

Indicates number of lines to be decompressed. 
genpalPhysical (GENPAL) 

Contains the physical palette. 
genpalVideo (GENPAL) 

Contains the video stream palette. 
rectlSrc (RECTL1) 

Contains the source window rectangle. 
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rectlDst (RECTL1) 

Contains the destination window rectangle. 

ulDeltaCount (ULONG) 

Number of remaining delta frames before the next key or reference frame. 


MMVIDEOHEADER 

This structure is the video track header, and it describes attributes of a video 
track for an open movie file. It is the standard presentation format for video 
data and is returned on an mmioGetHeader API. It is used on the 
mmioSetHeader API when the HMMIO refers to an open movie file and the 
active track for this file is set to a video track. 

Fields 

ulStructLen (ULONG) 

Indicates the length of entire structure. 
ulContentType (ULONG) 

The video content type is either MMIO_VIDEO_DATA or 

MMIOJVIDEO_UNKNOWN. MMIO_VIDEO_DATA is a recognized video 
type, MMIO_VIDEO_UNKNOWN is not supported. 

ulMediaType (ULONG) 

The video media type, MMIO_MEDIATYPE__DIGITALVIDEO. 
ulVideoCapsFlags (ULONG) 

Reserved for future use and must be set to zero, 
ulWidth (ULONG) 

Video width in pels. 
ulHeight (ULONG) 

Video height in pels. 
ulScale (ULONG) 

Number of time units per sample. 
ulRate (ULONG) 

Number of time units per second. 
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ulStart (ULONG) 

Specifies start time of the video. Normally it is zero, but it can specify a time 
for a stream that does not start concurrently with the movie file. 

ulLength (ULONG) 

The length of the movie file. 

ulTotalFrames (ULONG) 

Total number of video frames. 

ulInitialFrames (ULONG) 

Initial frame for interleaved files. Non-interleaved files should specify zero. 

mmtimePerFrame (MMTIME) 

Frame display time or OL. 
ulSuggestedBufferSize (ULONG) 

Suggested buffer size in bytes for reading the file. This field should be set to 
the maximum frame size for a movie. MMPM/2 will use this value to allo¬ 
cate data buffers for playing the movie. 

genpalVideo (GENPAL) 

A RGB palette table. 

pmmXDIBHeader (PMMXDIBHEADER) 

Pointer to the MMXDIBHEADER structure. 


MMVIDEOOPEN 

This structure contains information used on an MMIOM_CODEC_OPEN 
message call to a CODEC. It defines data constraint parameters to a video 
CODEC and is only used if the CODEC_DATA_CONSTRAINT flag is set in 
the ulCapFlags field of the CODECINIFILEINFO structure. The pOtherlnfo 
field of the CODECOPEN structure points to this structure. 


Fields 


ulStructLen (ULONG) 
Length of the structure. 
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ulQuality (ULONG) 

Indicates the quality of video compression. Range is 0-1000. If -1 is specified, 
the default is assumed. Upon successful completion, the current quality 
level is returned. 

ulKeyFrameRate (ULONG) 

Indicates key frame rate for compression. For example, 4 means there will 
be a key frame followed by 3 delta frames. If -1 is specified, the default is 
assumed. Upon successful completion the current key rate is returned. 

ulScale (ULONG) 

Number of time units per frame. If -1 is specified, the default is assumed. 
Upon successful completion the current scale is returned. 

ulRate (ULONG) 

Number of units per second. If -1 is specified, the default is assumed. Upon 
successful completion the current rate is returned. 

ulDataConstraint (ULONG) 

The maximum number of bytes allowed for the number of frames listed in 
ulConstraintlnterval. If -1 is specified, the default is assumed. Upon success¬ 
ful completion, the current constrained data rate is returned. 

ulConstraintlnterval (ULONG) 

Number of frames used to constrain the data rate specified in 
ulDataConstraint. If -1 is specified the default is assumed. On successful 
completion, the current constrained frame interval rate is returned. 


MMXDIBHEADER 

This structure is a sub-header for both the image and video header and is usu¬ 
ally contained within the MMIMAGEHEADER or MMVIDEOHEADER. It is 
part of the standard presentation format for image and video data and is 
returned on an mmioGetHeader API. It is used on the mmioSetHeader API 
when the HMMIO refers to an open image or movie file. 


Fields 


XDIBHeaderPrefix (XDIBHDR_PREFIX) 
Extension of OS/2 2.0 PM compatible header. 
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BMPInfoHeader2 (BITMAPINF0HEADER2) 
OS/2 2.0 PM Bitmap Compatibility Header. 


MMX WAV_H E AD E R 

This structure is a sub-header for the audio header and is usually contained 
within the MMAUDIOHEADER. It contains specific information about the 
digital audio content, including the format of the data representation for the 
data which it is associated. It is part of the standard presentation format for 
audio data and is returned on an mmioGetHeader API. It is used on the 
mmioSetHeader API when the HMMIO refers to an open audio, or to an open 
movie file when the active track for this file is set to a audio track. 


Fields 


WAVEHeader (WAVE.HEADER) 

Wave Header information as explained under WAVE Header. This field 
maps to the RIFF wave header. 

XWAVHeaderlnfo (XWAV.HEADERINFO) 

Includes additional audio parameters. 


PCODECPROC 

Pointer to a CODEC entry point. All CODEC messages are passed to a CODEC 
using this interface. The syntax for a direct CODEC procedure call is as 
follows: 


typedef LONG (APIENTRY C0DECPR0C) (PHCODEC phcodec, 

USHORT usMsg, 
LONG IParml, 

LONG 1Parm2); 

typedef CODECPROC ^PCODECPROC; 
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PMMIOPROC 

A pointer to an I/O procedure entry point. All I/O procedure messages are 
passed to a I/O procedure using this interface. The syntax for a direct I/O pro¬ 
cedure call is as follows: 


typedef LONG (APIENTRY MMIOPROC) (PVOID pmmioinfo, 

USHORT usMsg, 
LONG lParml, 
LONG 1Parm2); 

typedef MMIOPROC *PMMI0PR0C; 


QOS 


This structure defines generic parameters for the QOSInfo structure. It is 
used on an MMIOMJBEGINSTREAM message call to an I/O procedure. 


Fields 


lQOSParmld (LONG) 

Quality of service parameter ID can be one of the following: 

SERVICE.REQUEST —The requests the type service required for this 
stream. The IQOSValue field contains the type of service. 

MAX_EE_JITTER —The number of stream buffers for handling jitter. 
Buffers needed to store a single unit of data are separate. The IQOSValue 
field contains the number of buffers. 

MAX_DATA_RATE —Maximum data rate in bytes per second. The 
IQOSValue field contains this information. 

AVG_DATA_RATE —Average data rate in bytes per second. The 
IQOSValue field contains this information. 
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lQOSValue (LONG) 

The value of the quality of service parameter id specified in the 
IQOSParmld field. If the IQOSParmld field contains 
SERVICEJREQUEST, this field can be one of the following flags: 

GUARANTEED —The application requests guaranteed service if requested 
QOS is unavailable, the connection is not made. 

DONTCARE —The application requests the given QOS, but if it is unavail¬ 
able, a connection may be made without quality of service reservation. 

DONTRESERVE —The application does not want guarantees (same as no 
message). The remaining fields are meaningless and not examined. 


QOSInfo 

This structure defines a guaranteed bandwidth across networks supporting 
Quality of Service (QOS) and is used on an MMIOM_BEGINSTREAM mes¬ 
sage call to an I/O procedure. 


Fields 


INumQOSParms (LONG) 

Number of QOS data structure in the QOSParms[] field. 
QOSParmsfl] (QOS) 

Array of the QOS data structures. 


RECORDTAB 

This structure represents a single record of a buffer on a MMIOM_MULTI- 
TRACKREAD message call to an I/O procedure. An array of these structures 
is passed to the I/O procedure on a multitrack read request. The I/O procedure 
will use each entry in the array to point to an individual record of data read 
from a track of a movie file. The pRecordTabList field of the TRACKMAP 
structure points to this structure. This structure is another representation of 
the SRCBUFTAB structure. 
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Fields 


ulReservedl (ULONG) 

Reserved for system use. 
pRecord (PVOID) 

A pointer to a data record in pBuffer data buffer. 
ulLength (ULONG) 

The length of the data record in bytes. 
ulReserved2 (ULONG) 

Reserved for system use. 
ulReserved3 (ULONG) 

Reserved for system use. 
ulParml (ULONG) 

Data record specific data. This field can return one of the following flags on 

a MMIOM_MULTITRACKREAD message: 

MMIO_IS_KEY_FRAME —The data record contains a key or reference 
video frame. 

MMIO_IS_PALETTE —The data record contains a video palette. This 
data record is not considered a video frame. 

MMIO_INVISIBLE_FRAME —The data record contains a video frame 
that should not be displayed. This flag is part of the seek support for 
movies. It allows a movie to be “seeked” to a non-reference frame. This 
frame needs to be decoded, but should not be displayed. 

MMIO_NULL_FRAME —The data record contains a video frame of zero 
length. Some file formats contain these zero length video frame, or null 
frames, as filler for frames missed during capture of the movie, especially 
during real-time capture. 

ulParm2 (ULONG) 


Data of record-specific data. This field is used to return the video frame 
number for this video frame if this track is a video track. 
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RECORDTABWRITE 

This structure represents a single record of a data on a MMIOMJV1ULTI- 
TRACKWRITE message call to an I/O procedure. An array of these structures 
is passed to the I/O procedure on a multitrack write request. Each entry con¬ 
tains one record pointer to data, and the I/O procedure will write each record to 
a track of a movie file. The pRecordTabList field of the TRACKMAP structure 
points to this structure. This structure is another representation of the TGT- 
BUFTAB structure. 


Fields 


pRecord (PVOID) 

A pointer to a data record to write. 
ulReservedl (ULONG) 

Reserved for system use. 
ulLength (ULONG) 

The length of the data record in bytes. 
ulReserved2 (ULONG) 

Reserved for system use. 
ulReserved3 (ULONG) 

Reserved for system use. 
ulParml (ULONG) 

Data record-specific data. This field can contain one of the following flags on 

a MMIOM_MULTITRACKWRITE message: 

MMIO_IS_KEY_FRAME —The data record contains a key or reference 
video frame. 

MMIO_ISJPALETTE —The data record contains a video palette. This 
data record is not considered a video frame. 

ulParm2 (ULONG) 

Data record specific data. On a MMIOM_MULTITRACKWRITE message, 
this field must contain the number of NULL frames that should be inserted 
before this frame. This is used during real-time capture of video to save the 
number of missed (NULL) frames so that the video stream will playback at 
the correct rate. 
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RECTL 

This structure is a rectangle structure. 

Fields 

xLeft (LONG) 

x-coordinate of left-hand edge of a rectangle. 
yBottom (LONG) 

y-coordinate of bottom edge of a rectangle. 
xRight (LONG) 

x-coordinate of right-hand edge of a rectangle. 
yTop (LONG) 

y-coordinate of top edge of a rectangle. 

RECTL1 

This structure is a rectangle structure. 

Fields 

xLeft (LONG) 

x-coordinate of left-hand edge of a rectangle. 
yBottom (LONG) 

y-coordinate of bottom edge of a rectangle. 
xRight (LONG) 

x-coordinate of right-hand edge of a rectangle. 
yTop (LONG) 

y-coordinate of top edge of rectangle. 
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RGB2 

This structure is a color palette entry. 

Fields 

bBlue (BYTE) 

Blue component of the color definition. 
bGreen (BYTE) 

Green component of the color definition. 
bRed (BYTE) 

Red component of the color definition. 
fcOptions (BYTE) 

This field is reserved and must be set to 0. 


TRACKMAP 

This structure contains information used on an MMIOM__MULTITRACK- 
READ and MMIOM_MULTITRACKWRITE message call to an I/O proce¬ 
dure. It defines track specific information for one track. The pTrackMapList 
field of the MMMULTITRACKREAD and MMMULTITRACKWRITE struc¬ 
tures point to this structure. 


Fields 


ulTrackID (ULONG) 

A track identifier. 
ulNumEntries (ULONG) 

The number of entries in pRecordList. On output it returns the number. 
pRecordTabList (ULONG) 

A pointer to a table record. 
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WAVE_HEADER 

This structure is a sub-header for the audio header and is usually contained 
within the MMXWAV_HEADER. It contains descriptive information about 
the digital audio element, such as sample rate and bits per sample. It is part of 
the standard presentation format for audio data and is returned on an 
mmioGetHeader API. It is used on the mmioSetHeader API when the 
HMMIO refers to an open audio, or to an open movie file when the active track 
for this file is set to a audio track. 


Fields 


usFormatTag (USHORT) 

A number indicating the Wave format category of data. Valid values for this 
field are as follows: 

DATATYPE_WAVEFORM —Waveform audio (PCM)—This is the only 
valid value for standard presentation format. 

DATATYPE_ALAW —Alaw. 

DATATYPE_MULAW —MuLaw. 

DATATYPE_ADPCM_AVC —ADPCM audio. 

usChannels (USHORT) 

Number of channels represented in the waveform data; Channel 1 for 
monaural and Channel 2 for stereo. 

CH_1 —Mono. 

CH_2 —Stereo. 

CH_3 —Quad. 

ulSamplesPerSec (ULONG) 

Sampling rates, in kilohertz, which each channel should be played. Not all 
audio hardware support all sampling rates. Some predefined values for stan¬ 
dard audio presentation are: 

HZ_8000— 8.000 kKHZ 

HZ_11025— 11.025 KHZ 

HZ_14700 —14.700 KHZ (SPV/2) 
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HZ_18900 —18.900 KHZ (CD/XA LVL C) 

HZ__22050— 22.050 KHZ 
HZ_37800— 37.800 KHZ (CD/XA LVL C) 

HZ_44100 —44.100 KHZ 
ulAvgBytesPerSec (ULONG) 

The rate at which the waveform data should be transferred. Playback soft¬ 
ware can estimate the buffer size by using this value. The following formula 
can be used to calculate this value for the audio presentation format of stan¬ 
dard PCM data: 

usChannels x ulSamplesPerSec x usBitsPerSample / 8 

usBlockAlign (USHORT) 

Denotes block alignment, in bytes of the waveform data. Playback software 
needs to process a multiple of usBlockAlign bytes of data at a time. This 
value can be used for buffer alignment. It should be determined by the fol¬ 
lowing formula for audio presentation format of standard PCM data: 

usChannels x usBitsPerSample / 8 

usBitsPerSample (USHORT) 

Number of bits of data used to represent each sample of each channel. If 
multiple channels are used, the sample size is the same for each channel. 

BPS_4 —4 bits/sample (ADPCM) 

BPS_8 —8 bits/sample (PCM) 

BPS_16 —16 bits/sample (PCM) 


XDIBHDR_PREFIX 

This structure is a sub-header for both the image and video header and is usu¬ 
ally contained within the MMXDIBHEADER. It is part of the standard pre¬ 
sentation format for image and video data, and it is returned on an 
mmioGetHeader API. It is used on the mmioSetHeader API when the 
HMMIO refers to an open image or movie file. 


Fields 


ulMemSize (ULONG) 
Size of the bitmap bits. 
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ulPelFormat (ULONG) 

Specifies the FOURCC code defining the pel format of the bitmap data. 
Valid values for this field would be as follows for the standard image presen¬ 
tation format: 

‘rgbb’ —Pel format is packed, unpalletized, 24-bit RGB. 

‘palb 9 —Pel format is 1, 4, or 8-bit palletized data, depending on the value 
in the cBitCount field. 

usTransType (USHORT) 

Denotes transparency color. This field is currently not used in the standard 
presentation format. 

ulTransVal (ULONG) 

Transparent color indicator. This field is currently not used in the standard 
presentation format. 


XWAV_HEADERINFO 

This structure is a sub-header for the audio header and is usually contained 
within the MMXWAV_HEADER. It contains information about the length of 
the audio data. It is part of the standard presentation format for audio data 
and is returned on an mmioGetHeader API and is used on the 
mmioSetHeader API when the HMMIO refers to an open audio or to an open 
movie file when the active track for this file is set to a audio track. 

Fields 


ulAudioLengthlnMS (ULONG) 

Total length of the audio data in miliseconds, or 0. Use of this field is 
optional. 

ulAudioLengthlnBytes (ULONG) 

Total length of the audio data is bytes, or 0. Use of this field is optional. 
ulReserved (ULONG) 

Reserved for future use and must be set to zero. 
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REXX Interfaces 


This section provides a listing of the REXX APIs for access to the MMPM/2 
functions. 

mciRxGetDevicelD 


mciRxGetDevicelD 

Get the device ID corresponding to an alias of a device. 

rc = mciRxGetDevicelD(a 1ias) 

Parameters 

alias —input 

The device alias that was specified on a previous open command. 

Return Values 

Returns a device ID number. If 0 is returned, then this is an error. 
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mciRxGetErrorString 


m c i RxGetE r ro rStri n g 

Get the textual string associated with the given error code. 


rc = mciRxGetErrorString(rc, ‘errorstring’) 


Parameters 

rc —input 

Returns code from the mciRxSendString function, 
errorstring— output 

REXX variable name to store the returned error string associated with the 
error rc. 

Return Values 

Returns 0 if successful, otherwise an error number will be returned. 

Remarks 

If the error return code from this function is 0, an error return string is stored 
in the errorstring variable. 



APPENDIX C: REXX Interfaces 729 


mciRxExit 


mciRxExit 

This function terminates MMPM/2 support for a REXX command file. 

rc = mciRxExit 

Parameters 

None. 

Return Values 

Returns 0 if successful, otherwise an error is returned. 

Remarks 

This function must be called to release resources used by the MMPM/2 
functions. 
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mciRxInit 


mciRxInit 

This function initializes a REXX command file so that MCI string commands 
may be used. 

rc = mciRxSendString(commandstring, “retstring”, reservedl, reserved2) 

Parameters 

None. 

Return Values 

Returns 0 if successful, otherwise an error number will be returned. 

Remarks 

This function must be registered in REXX. 
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mciRxSencJString 

mciRxSendSfring 

This function sends a Media Control Interface Command String to MMPM/2. 

rc = mciRxSendString(commandstring, “retstring”, reservedl, reserved2) 


Parameters 

commandstring —input 

MCI command string to execute, 
returnstring —output 

REXX variable to store the return string (if any) from the MCI string exe¬ 
cuted. This variable must be enclosed in quotes. 

reservedl —input 

Reserved, must be 0. 

reserved2 —input 

Reserved, must be 0. 

Return Values 

This function will return 0 if the command is executed successfully, otherwise 
an error number will be returned. See the individual Media Control Interface 
messages for the possible error codes. 
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Secondary Windows 


This section describes the MMPM/2 secondary window control APIs. 

WinCreateSecondaryWindow 


WinCreateSecondaryWindow 

This function creates a secondary window from a dialog template in memory. 


#define INCL_SW 
#include <os2me.h> 

HWND WinCreateSecondaryWindow (HWND hwndParent, 

HWND hwndOwner, 
PFNWP pfnDlgProc, 
PDLGTEMPLATE pdlgt, 
PVOID CreateParams) 


Parameters 

hwndParent (HWND)—input 

The parent window handle of the secondary window to be created. 
hwndOwner (HWND)—input 

The owner-window handle of the secondary window to be created. 
pfnDlgProc (PFNWP)—input 
The secondary window procedure. 
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pdlgt (PDLGTEMPLATE)—input 

The dialog template that defines the layout of the window. 

CreateParams (PVOID)—input 

The parameters passed to the secondary window procedure on the 
WM_INITDLG message. 

Return Values 

hwndRC (HWND)—returns 

Returns the frame window handle to a secondary window. 

Remarks 

See WinCreateDlg in the IBM OS/2 2.1 Presentation Manager Programming 
Reference. 
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WinDefSecondaryWindowProc 


WinDefSecondaryWindowProc 

This function provides the default behavior for a secondary window. 


#define INCL_SW 
#include <os2me.h> 

HWND WinDefSecondaryWindowProc (HWND hwnd, 

ULONG ulmsg 
MPARAM mpl, 
MPARAM mp2) 


Parameters 

hwnd (HWND)—input 
Dialog window handle, 
ulmsg (ULONG)—input 
Message identity, 
mpl (MPARAM)—input 
Parameter 1. 
mp2 (MPARAM)—input 
Parameter 2. 

Return Values 

mresRC (MRESULT)—returns 

Returns the Mresults defined by the message passed to this function. 

Remarks 

A secondary window procedure must reference this function for messages that 
are not handled explicitly. See WinDefDlgProc in the IBM OS/2 2.1 
Presentation Manager Programming Reference. 
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WinDefaultSize 


WinDefaultSize 

This function sizes the window to its default size - the optimal size of the dialog 
window. 


//define INCL_SW 
//include <os2me.h> 

HWND WinDefaultSize (HWND hwnd) 


Parameters 

hwnd (HWND)—input 
Secondary window handle. 

Return Values 

fRC (BOOL)—returns 

TRUE if successful, otherwise FALSE. 

Remarks 

Sizes the window to its recommended optimal size. 



APPENDIX D: Secondary Windows 737 

WinDestroySecondaryWindow 


WinDestroySecondaryWindow 

This function eliminates a secondary window. 


//define INCL_SW 
//include <os2me.h> 

HWND WinDestroySecondaryWindow (HWND hwnd) 


Parameters 

hwnd (HWND)—input 

Secondary window frame to be destroyed. 

Return Values 

fRC (BOOL)—returns 

TRUE if successful, otherwise FALSE. 
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WinDismissSecondaryWindow 


WinDismissSecondaryWindow 

This function causes modal WinProcessSecondaryWindow or 
WinSecondaryWindow calls to return. 


#define INCL_SW 
#include <os2me.h> 

BOOL WinDismissSecondaryWindow (HWND hwndDlg, 

ULONG ulResult) 


Parameters 

hwndDlg (HWND)—input 
Secondary Dialog window. 
ulResult (ULONG)—input 

Result to be returned by WinSecondaryWindow or 
WinProcessSecondaryWindow. 

Return Values 

fRC (BOOL)—returns 

TRUE if successful, otherwise FALSE. 


Remarks 

See WinDismissDlg in the IBM OS/2 2.1 Presentation Manager 
Programming Reference. 
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WinlnsertDefaultSize 


WinlnsertDefaultSize 

This function adds the default size function to the system menu of a secondary 
window. 


//define INCL_SW 
//include <os2me.h> 

HWND WinlnsertDefaultSize (HWND hwnd, 

PSZ DefaultSize) 


Parameters 

hwnd (HWND)—input 
Secondary window handle. 

Defaultsize (PSZ)—input 

Text to be inserted into the system menu. Usually this will read “Default 
Size.” 

Return Values 

fRC (BOOL)—returns 

TRUE if successful, otherwise FALSE. 


Remarks 

This function adds Default Size to the system menu of a secondary window. 
Because a secondary window is a sizable dialog, its initial size is the optimal 
size for the dialog. After the window is sized, scroll bars appear when neces¬ 
sary. The default size function returns the window to its optimal size. 



740 Developing Multimedia Applications Under OS/2 


WinLoadSecondaryWindow 


WinLoadSecondaryWindow 

This function creates a secondary window from a dialog template in a resource. 
The secondary window is modeless. 


#define INCL_SW 
^include <os2me.h> 

HWND WinLoadSecondaryWindow (HWND hwndParent, 

HWND hwndOwner, 
PFNWP pfnDlgProc, 
HMODULE hmod, 

ULONG idDlg, 

PVOID CreateParams) 


Parameters 

hwndParent (HWND)—input 

Parent-window handle of the created secondary frame window. 
hwndOwner (HWND)—input 

Requested owner-window handle of the created secondary frame. 
pfnDlgProc (PFNWP)—input 

Secondary window procedure for the created dialog window. This is a dialog 
procedure, except that it calls WinDefSecondaryWindowProc. 

hmod (HMODULE)—input 

Module handle for resource module. 

idDlg (ULONG)—input 

Resource ID of dialog template in the resources of the module hmod. 
CreateParams (PVOID)—input 

Passed to the secondary window procedure in the WMJNITDLG message. 

Return Values 

fRC (BOOL)—returns 

TRUE if successful, otherwise FALSE. 
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Remarks 

This call creates a standard frame window with a dialog window as the child of 
the FID__CLIENT window. See WinLoadDlg in the IBM OS/2 2.1 
Presentation Manager Programming Reference. 
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WinProcessSecondaryWindow 


WinProcessSecondaryWindow 

This function process a modal secondary window by dispatching messages 
while the modal window is displayed. 


//define INCL_SW 
//include <os2me.h> 

HWND WinProcessSecondaryWindow (HWND hwndSW) 


Parameters 

hwndSW (HWND)—input 

Secondary frame window handle to process. 

Return Values 

ulRC (ULONG)—returns 

Returns the result passed to WinDismissSecondaryWindow. 
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WinQuer ySeconda ry H WN D 


WinQuerySecondaryHWND 

This function returns a window handle to various windows created as a part of 
a secondary window. 


#define INCL_SECONDARYWINDOW 
#include <os2me.h> 

HWND WinQuerySecondaryHWND (HWND hwnd, 

ulong ULfLAG) 


Parameters 

hwndParent (HWND)—input 
Secondary window handle. 
ulFlag (LONG)—input 

QS.FRAME Returns the HWND for the outer standard frame window. 
QS.DIALOG Returns the HWND for the inner dialog frame window. 

Return Values 

hwndRC (HWND)—returns 

Returns the requested window handle. 


Remarks 

This function returns the handle to the outer frame window or the inner dialog 
frame window of a secondary window, depending upon the handle supplied as 
input. Secondary windows utilize two frame windows; a standard frame and a 
dialog window to implement the sizing and scrolling features. The window 
handle returned from WinLoadSecondaryWindoiv is the handle to the stan¬ 
dard frame. The window handle passed to the message procedure specific in 
WinLoadSecondaryWindoiv is the dialog window handle. The standard 
frame window handle must be used when associating a help instance and to do 
WinSetWindoivPos operations. The dialog window handle should be used as 
the owner for message boxes and to access the controls on the dialog with 
WinWindowFromID . To modify the title bar or the system menu, the applica¬ 
tion must specify the standard frame window and not the dialog window. 
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WinSecondaryMessageBox 


WinSecondaryMessageBox 

This function creates a modal window, similar to WinMessageBox , that can be 
used to display error messages and ask questions. 


#define INCL_SW 
#iinclude <os2me.h> 

BOOL WinSecondaryMessageBox (HWND hwndParent, 

HWND hwndOwner, 

PSZ Text, 

PSZ Caption, 

ULONG isWindow, 
PSMBINFO psmbinfo) 


Parameters 

hwndParent (HWND)—input 

The parent window handle of the secondary window to be created. 
hwndOwner (HWND)—input 

The owner window handle of the secondary window to be created. 

Text (PSZ)—input 

The text of the message to be displayed. 

Caption (PSZ)—input 

The title of the secondary message box window. 
idWindow (ULONG)—input 

The identifier of the secondary message box window, 
psmbinfo (PSMBINF)—input 

This is an information block that defines which buttons must be included in 
the window. 
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Return Values 

ulRC (ULONG)—returns 

Returns the result passed to WinDismissSecondaryWindow ; this is the ID of 
the button that was clicked. 

Remarks 

See WinMessageBox in the IBM OS/2 2.1 Presentation Manager 
Programming Reference. 
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Wi nSecondaryWi ndow 


WinSecondaryWindow 

This function loads and processes a modal secondary window and returns the 
result value established by WinDismissSecondaryWindow. 


#define INCL_SW 
#include <os2me.h> 

BOOL WinSecondaryWindow (HWND hwndParent, 

HWND hwndOwner, 
PFNWP pfnDlgProc, 
HMODULE hmod, 

USHORT idDlg, 

PVOID CreateParams) 


Parameters 

hwndParent (HWND)—input 

The parent window handle of the CreateSecondaryWindow frame. 
hwndOwner (HWND)—input 

The owner window handle of the CreateSecondaryWindow frame. 
pfnDlgProc (PFNWP)—input 

The secondary window procedure for CreateDialogWindow. This is a dia¬ 
log procedure, except that it calls WinDefSecondaryWindowProc. 

hmod (HMODULE)—input 

Module handle for resource module. 

idDlg (USHORT)—input 

Resource ID of dialog template in the resources of the module hmod. 
CreateParams (PVOID)—input 

This is passed to the secondary window procedure in the WM_INITDLG 
message. 
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Return Values 

ulRC (ULONG)—returns 

Returns the result passed to WinDismissSecondaryWindow ; this is the ID of 
the button that was clicked. 

Remarks 

This call creates a standard frame window with dialog window as the child of 
FID_CLIENT. See WinDlgBox in the IBM OS/2 2.1 Presentation Manager 
Programming Reference. 



748 Developing Multimedia Applications Under OS/2 


SMBD 

This structure defines the button style, text, and ID for each button to be 
included in a secondary message box. 


typedef structure _SMBD { 

CHAR chText; 

ULONG ulButton; 

USHORT usStyle; 

}SMBD; 


Fields 


chText (CHAR) 

Text of the button. 
ulButton (ULONG) 

Button ID returned when user chooses. 
usStyle (USHORT) 

Button style. 


SMBINFO 


This structure defines the icon, number of buttons, and window style of the 
secondary message box. 


typedef structure 

HPOINTER 

ULONG 

ULONG 

PSMBD 

}SMBINFO; 


_SMBINFO { 

hptrlcon; 
ulButtons; 
ulStyle; 
psmbd; 
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Fields 

hptrlcon (HPOINTER) 

Icon handle. 
ulButtons (ULONG) 

Number of buttons. 
usStyle (ULONG) 

Message box style: 

MB ^INFORMATION Information Icon. 
MB_QUERY Question Icon. 

MB_WARNING Warning Icon. 

MB_ERROR Error Icon. 

MBJCONCUSTOM Custom Icon, 
psmbd (PSMBD) 

Array of button definitions. 
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MMPM/2 Errors 


Message 

Error 

Number 

Description 

MCIERR_SUCCESS 

0 

MMPM Command completed 
successfully. 

MCIERR_INVALID_DEVICE_ID 

5001 

Invalid device ID given. 

MCIERR_NO_MASTER 

5002 

Unable to find a Master. 

MCIERR_UNRECOGNIZED_KEYWORD 

5003 

Unrecognized keyword given in 
command string. 

MCIERR_MASTER_CONFLICT 

5004 

More than one device can ONLY 
be a Master. 

MCIERR_UNRECOGNIZED_COMMAND 

5005 

Unrecognized command. 

MCIERR_HARDWARE 

5006 

Hardware error. 

MCIERR_INVALID_DEVICE_NAME 

5007 

Invalid Device Name given. 

MCIERR_OUT_OF_MEMORY 

5008 

System out of memory. 

MCIERR_DEVICE_OPEN 

5009 

Device is already open. 

MCIERR_CANN OT_LO AD_DRIVER 

5010 

Cannot load MMPM2 driver. 

MCIERR_MISSING_COMMAND_STRING 

5011 

Missing command string. 
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Message 

Error 

Number 

Description 

MCIERR_PARAM_OVERFLOW 

5012 

Parameter overflow. 

MCIERR_MISSING_STRING_ARGUMENT 

5013 

Missing required string argu¬ 
ment. 

mcierr_bad_integer 

5014 

Bad Integer given in command 
string. 

MCIERR_PARSER_INTERNAL 

5015 

Internal MMPM2 parser error. 

MCIERR_DRIVER_INTERNAL 

5016 

Internal MMPM2 driver error. 

MCIERR_MISSING_PARAMETER 

5017 

Missing parameter for this com¬ 
mand. 

MCIERR_UN SUPPORTED_FUN CTION 

5018 

Function not supported by the 
MCI driver being used. 

MCIERR_FILE_N OT_FOUND 

5019 

File not found. 

MCIERR_DEVICE_NOT_READY 

5020 

Device is not ready. 

MCIERR_INTERNAL 

5021 

MMPM2 internal error. 

MCIERR_DRIVER 

5022 

Internal MMPM driver error. 

MCIERR_C ANN OT_U SE_ALL 

5023 

Cannot use ALL keyword with 
this command. 

MCIERR_MULTIPLE 

5024 

Multiple defined. 

MCIERR_EXTENSION_NOT_FOUND 

5025 

Extension not found. 

MCIERR_OUTOFRANGE 

5026 

Value given is out of range. 

MCIERR_CANNOT_ADD_ALIAS 

5027 

Cannot add Alias. 

MCIERR_FLAGS_NOT_COMPATIBLE 

5028 

Flags not compatible. 

MCIERR_CANNOT_USE_NOUNLOAD 

5029 

Cannot use NOUNLOAD flag on 
this command. 

MCIERR_FILE_NOT_SAVED 

5030 

File not saved. 

MCIERR_DEVICE_TYPE_REQUIRED 

5031 

Device type required. 

MCIERR_DEVICE_LOCKED 

5032 

Device is locked. 
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Message 

Error 

Number 

Description 

MCIERR_DUPLICATE_ALIAS 

5033 

Duplicate alias. 

MCIERR_IN STAN CE_INACTIVE 

5034 

Instance inactive. 

MCIERR_COMMAND_TABLE 

5035 

Command table error. 

MCIERR_INI_FILE_LOCKED 

5037 

The MMPM2.INI File is currently 
Locked. 

MCIERR_NO_AUDIO_SUPPORT 

5040 

No audio support present. 

MCIERR_NOT_IN_PM_SESSION 

5041 

Not currently in a Presentation 
Manager Session. 

MCIERR_DUPLICATE_KEYWORD 

5042 

Duplicate keyword in command 
string. 

MCIERR_COMMAND_STRING_OVERFLOW 

5043 

Command string to long. 

MCIERR_DRIVER_PROC_N OT_FOUND 

5044 

MMPM2 driver procedure address 
not found. 

MCIERR_INVALID_DEVICE_TYPE 

5045 

Invalid device type given. 

MCIERR_INVALID_DEVICE_ORDINAL 

5046 

Invalid Device ordinal given. 

MCIERR_HEADPHONES_NOT_SET 

5047 

Headphones not set on. 

MCIERR_SPE AKERS_N OT_SET 

5048 

Speakers not set on. 

MCIERR_SOUND_NOT_SET 

5049 

Mute on. 

MCIERR_INVALID_BUFFER 

5050 

Invalid return buffer given. 

MCIERR_INVALID_MEDIA_TYPE 

5051 

Invalid media type given. 

MCIERR_INVALID_CONNECTOR_INDEX 

5052 

Invalid connector index. 

MCIERR_NO_CONNECTION 

5053 

No connection found. 

MCIERR_INVALID_FLAG 

5054 

Invalid flag specified for this com¬ 
mand. 

MCIERR_CANNOT_LOAD_DSP_MOD 

5055 

DSP module not found. 

MCIERR_ALREADY_CONNECTED 

5056 

The connection already exists. 
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Message 

Error 

Number 

Description 

MCIERR_INVALID_CALLBACK_HANDLE 

5057 

The window callback handle is 
invalid. 

MCIERR_DRIVER_N OT_FOUND 

5058 

MMPM2 driver not found. 

MCIERR_DUPLICATE_DRIVER 

5059 

Duplicate MMPM2 driver found. 

MCIERR_INI_FILE 

5060 

MMPM2.INI file error. 

MCIERR_INVALID_GROUP_ID 

5061 

Invalid group ID given. 

MCIERR_ID_ALREADY_IN_GROUP 

5062 

Device ID already in group. 

MCIERR_MEDIA_CHANGED 

5063 

Media has been changed. 

MCIERR_MISSING_FLAG 

5064 

Flag missing for this MMPM2 
command. 

MCIERR_UN SUPPORTED_FLAG 

5065 

Flag not supported by this 
MMPM2 driver for this command. 

MCIERR_DRIVER_NOT_LOADED 

5066 

MMPM2 driver is not loaded. 

MCIERR_INVALID_MODE 

5067 

Device mode is invalid for this 
command. 

MCIERR_INVALID_ITEM_FLAG 

5068 

Invalid item flag specified for this 
command. 

MCIERR_INVALID_TIME_FORMAT_FLAG 

5069 

Invalid time format flag specified 
for this command. 

MCIERR_SPEED_FORMAT_FLAG 

5070 

Invalid speed format flag specified 
for this command. 

MCIERR_INVALID_AUDIO_FLAG 

5071 

Invalid audio flag specified for 
this command. 

MCIERR_NODEFAULT_DEVICE 

5072 

No default device specified. 

MCIERR_DUPLICATE_EXTENSION 

5073 

Duplicate Extension specified. 

MCIERR_FILE_ATTRIBUTE 

5074 

File Attribute error specified. 

MCIERR_DUPLICATE_CUEPOINT 

5075 

Duplicate cuepoint given. 

MCIERR_INVALID_CUEPOINT 

5076 

Invalid cuepoint given. 
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Message 

Error 

Number 

Description 

MCIERR_CUEPOINT_LIMIT_REACHED 

5077 

Cuepoint limit reached. 

MCIERR_MISSING_ITEM 

5078 

Item flag missing for this com¬ 
mand. 

MCIERR_MISSING_TIME_FORMAT 

5079 

Time format flag missing for this 
command. 

MCIERR_MISSING_SPEED_FORMAT 

5080 

Speed format flag missing for this 
command. 

MCIERR_INVALID_CONNECTOR_TYPE 

5081 

Invalid connector type given. 

MCIERR_TARGET_DEVICE_FULL 

5082 

Target device is full. 

MCIERR_UN SUPPORTED_CONN_TYPE 

5083 

Connector type is not supported 
by this device. 

MCIERR_CANN OT_MODIFY_CONNECTOR 

5084 

Cannot enable or disable this con¬ 
nector. 

MCIERR_RECORD_ABORTED 

5085 

Record has been aborted. 

MCIERR_GROUP_COMMAND 

5086 

One or more devices in group 
failed command. 

MCIERR_DEVICE_NOT_FOUND 

5087 

Device cannot be found. 

MCIERR_RESOURCE_NOT_AVAILABLE 

5088 

Device Resource is not available. 

MCIERR_INVALID_IO_PROC 

5089 

Invalid MMIO proc given. 

MCIERR_WAVE_OUTPUTSINUSE 

5090 

Output is in use. 

MCIERR_WAVE_SETOUTPUTINUSE 

5091 

Output is in use. 

MCIERR_WAVE_INPUTSINU SE 

5092 

Input is in use. 

MCIERR_WAVE_SETINPUTINU SE 

5093 

Input is in use. 

MCIERR_WAVE_OUTPUTUNSPECIFIED 

5094 

Output not specified. 

MCIERR_WAVE_INPUTUNSPECIFIED 

5095 

Input not specified. 

MCIERR_WAVE_OUTPUTSUN SUITABLE 

5096 

Output is not suitable. 

MCIERR_WAVE_SETOUTPlJTUNSUITABLE 

5097 

Output is not suitable. 
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Message 

Error 

Number 

Description 

MCIERR_WAVE_INPUTSUN SUITABLE 

5098 

Input is not suitable. 

MCIERR_WAVE_SETINPUTUN SUITABLE 

5099 

Input is not suitable. 

MCIERR_SEQ_DIV_INCOMPATIBLE 

5100 

Division format is not compatable 
with this device. 

MCIERR_SEQ_PORT_INUSE 

5101 

Port in use. 

MCIERR_SEQ_PORT_NONEXISTENT 

5102 

Port does not exist for this device. 

MCIERR_SEQ_PORT_MAPNODEVICE 

5103 

MIDI mapper device does not 
exist. 

MCIERR_SEQ_PORT_MISCERROR 

5104 

Port error. 

MCIERR_SEQ_TIMER 

5105 

MIDI timer error. 

MCIERR_VDP_COMMANDCANCELLED 

5106 

MMPM2 command was cancelled 
by another MCI command 

MCIERR_VDP_COMMANDFAILURE 

5107 

MMPM2 command failed 

MCIERR_VDP_NOTSPUNUP 

5108 

MMPM2 command requires the 
videodisc player to be spunup 

MCIERR_VDP_NOCHAPTER 

5109 

MMPM2 command requires the 
videodisc to have chapters 

MCIERR_VDP_NOSIDE 

5110 

Videodisc side cannot be deter¬ 
mined 

MCIERR_VDP_NOSIZE 

5111 

Videodisc size cannot be deter¬ 
mined 

MCIERR_VDP_INVALID_TIMEFORMAT 

5112 

MMPM2 command does not sup¬ 
port the time format 

MCIERR_CLIPBOARD_ERROR 

5114 

A problem with the clipboard 
occurred. 

MCIERR_CANNOT_CONVERT 

5115 

Unable to convert clipboard for¬ 
mat. 

MCIERR_CANNOT_REDO 

5116 

Cannot redo previous action. 

MCIERR_CANNOT_UNDO 

5117 

Cannot undo previous action. 
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Message 

Error 

Number 

Description 

MCIERR_CLIPBOAED_EMPTY 

5118 

The clipboard is currently empty. 

MCIERR_INVALID_WORKPATH 

5119 

Work Path given is not a valid 
OS2 path 

MCIERR_INDETERMINATE_LENGTH 

5120 

Cannot determine length. 

MCIERR_DUPLICATE_EA 

5121 

An Extended Attribute of this 
type already exists for another 
device. 

MCIERR_INVALID_CONNECTION 

5122 

This connection is not valid. 

MCIERR_CHANNEL_OFF 

5123 

Primary channel has been turned 
off. 

MCIERR_C ANN OT_CHAN GE_CHANNEL 

5124 

Can not change this channel. 

MCIERR_FILE_IO 

5125 

Error occurred during file 
read/write. 

MCIERR_SYSTEM_FILE 

5126 

Could not find VSH data for RTV 
record. 

MCIERR_DISPLAY_RESOLUTION 

5127 

Display resolution not supported 
by ActionMedia™ II adapter. 

MCIERR_N 0_ASYN C_PLAY_ACTIVE 

5128 

Currently there is no asynchro¬ 
nous play active. 

MCIERR_UN SUPP_FORMAT_TAG 

5129 

Unsupported format tag. 

MCIERR_UNSUPP_SAMPLESPERSEC 

5130 

Unsupported sampling rate. 

MCIERR_UNSUPP_BITSPERS AMPLE 

5131 

Unsupported bits per sample. 

MCIERR_UNSUPP_CHANNELS 

5132 

Unsupported number of channels. 

MCIERR_UNSUPP_FORMAT_MODE 

5133 

Unsupported format mode. 

MCIERR_NO_DEVICE_DRIVER 

5134 

No device driver found. 

MCIERR_CODEC_NOT_SUPPORTED 

5135 

Codec can not be found or cannot 
support the current video mode. 

ERROR_INVALID_STREAM 

5501 

Invalid stream handle specified. 
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Message 

Error 

Number 

Description 

ERRORJNVALID.HID 

5502 

Invalid handler id specified. 

ERROR_INVALID_OBJTYPE 

5504 

Invalid object type specified. 

ERROR_INVALID_FLAG 

5505 

Invalid flag specified. 

ERROR_INVALID_E VCB 

5506 

Invalid Event Control Block. 

ERROR_INYALID_EVENT 

5507 

Invalid event type or handle spec¬ 
ified. 

ERROR_INVALID_MMTIME 

5508 

Invalid mmtime specified. 

ERROR_INVALID_NUMSLAVES 

5509 

Invalid number of slaves speci¬ 
fied. 

error_invalid_request 

5510 

Invalid function requested. 

ERROR_INVALID_SPCBKEY 

5511 

Invalid Stream Protocol Key spec¬ 
ified. 

ERROR_INVALID_HNDLR_NAME 

5512 

Invalid stream handler name 
specified. 

ERROR_INVALID_PROTOCOL 

5513 

Invalid Stream Protocol specified. 

ERROR_INVALID_BUFFER_SIZE 

5514 

Invalid buffer size specified. 

error_invalid_buffer_returned 

5515 

Invalid buffer address returned. 

ERROR_INVALID_ACB 

5516 

Invalid Associate Control Block. 

ERROR_INVALID_RECORD_RETURNED 

5517 

Invalid record address returned. 

ERROR_STREAM_NOT_OWNER 

5599 

Not owner of stream. 

ERROR_STREAM_USED 

5600 

Stream already used in sync 
group. 

ERROR_STREAM_CREATION 

5601 

Error during stream creation. 

ERROR_STREAM_N OTMASTER 

5602 

Stream is not master stream of 
sync group. 

ERROR_STREAM_NOT_STOP 

5603 

Stream is not stopped. 

ERROR_STREAM_OPERATION 

5604 

Error in stream operation. 
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Error 

Number 

Description 

ERROR_STREAM_STOP_PENDING 

5605 

Stop stream is already in 
progress. 

ERROR_STREAM_ALREADY_STOP 

5606 

Stream has already been stopped. 

ERROR_STREAM_ALREADY_PAUSE 

5607 

Stream has already been paused. 

ERROR_STREAM_NOT_STARTED 

5608 

Stream has not been started. 

ERROR_STRE AM_N OT_ACTIVE 

5609 

Stream is not active. 

ERROR_START_STREAM 

5610 

Error starting stream. 

ERROR_MASTER_USED 

5611 

Master stream used in another 
sync group. 

ERROR_SPCBKEY_MISMATCH 

5612 

SPCB key is mismatched. 

ERROR_IN SUFF_BUFFER 

5613 

Insufficient buffer size specified. 

error_alloc_resources 

5614 

Unable to allocate resources. 

ERROR_ACCESS_OBJECT 

5615 

Unable to access the object speci¬ 
fied. 

ERROR_HNDLR_REGISTERED 

5616 

Stream Handler already regis¬ 
tered. 

ERROR_DATA_ITEM_NOT_SPECIFIED 

5617 

Data item has not been specified. 

ERROR JNVALID.SEQUENCE 

5618 

Invalid sequence of events 
occurred. 

ERRORJNITIALIZATION 

5619 

Error during initialization. 

ERROR_RE ADIN G_INI 

5620 

Error reading the SPI.INI file. 

ERROR_LOADING_HNDLR 

5621 

Error loading a Stream Handler. 

ERROR_HNDLR_N OT_FOUND 

5622 

Stream Handler not found in sys¬ 
tem. 

ERROR_SPCB_N OT_FOUND 

5623 

SPCB not found. 

ERROR_DE VICE_N OT_FOUND 

5624 

Device not found. 

ERROR_TOO_MANY_E VENTS 

5625 

Too many events for event queue. 
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Message 

Error 

Number 

Description 

ERROR JDEVICE.OVERRUN 

5626 

Device overrun occurred. 

ERROR JDEVICE_UNDERRUN 

5627 

Device underrun occurred. 

ERROR_HNDLR_N OT_IN_INI 

5628 

Stream Handler not found in 
SPI.INI file. 

ERROR_QUERY_STREAM_TIME 

5629 

Time not available for this 
stream. 

ERROR_DATA_ITEM_NOT_SEEKABLE 

5630 

Data item cannot be seeked. 

ERROR_N OT_SEEKABLE_BY_TIME 

5631 

Not seekable by time. 

ERROR_N OT_SEEKABLE_B Y_B YTE S 

5632 

Not seekable by bytes. 

ERROR_STREAM_NOT_SEEKABLE 

5633 

Stream cannot be seeked. 

ERROR_PLAYLIST_STACK_OVERFLOW 

5635 

Playlist stack overflow. 

ERROR_PLAYLIST_STACK_UNDERFLOW 

5636 

Playlist stack underflow. 

ERROR_LOCKING_BUFFER 

5637 

Error locking down buffer. 

ERROR_UNLOCKING_BUFFER 

5638 

Error unlocking buffer. 

ERROR_SEEK_PAST_END 

5639 

Seek past end of object. 

ERROR_SEEK_BACK_NOT_SUPPORTED 

5640 

Seek back not supported. 

ERROR_INTERNAL_ERROR 

5641 

Internal memory error occurred. 

ERROR_INTERNAL_CORRUPT 

5642 

Internal memory pool corrupted. 

ERROR_IN SUFF_MEM 

5643 

Insufficient memory. 

ERROR_LARGE_SEEK_BY_TIME 

5644 

Large seek by time. 

ERROR_STRE AM_PREROLLIN G 

5645 

Function not allowed while pre¬ 
rolling. 

ERROR_INI_FILE 

5646 

Error encountered in SPI.INI file. 

ERROR_SEEK_BEFORE_BEGINNIN G 

5647 

Attempt to seek before beginning 
of object. 

ERRORJTOOJVtANYJEiANDLERS 

5648 

Stream Handler table full. 
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Error 

Number 

Description 

ERROR_ALLOC_HEAP 

5649 

Error allocating memory from 
heap. 

ERROR J5ND_0FJPLAYLIST 

5650 

End of playlist encountered. 

ERROR_TOO_MANY_STREAMS 

5651 

Too many streams active. 

ERROR_FILE_FORMAT_INCORRECT 

5652 

File format incorrect. 

ERROR_DESTROY_STREAM 

5653 

Error destroying stream. 

ERROR_INVALID_NUMMASTERS 

5654 


ERROR_MASTER_CONFLICT 

5655 


ERROR_N 0_MASTER 

5656 


ERROR_N 0_SYN C 

5657 


ERROR_BUFFER_NOT_AVAILABLE 

5900 

Buffer is not available. 

ERROR_TOO_MANY_BUFFERS 

5901 

Too many buffers. 

ERROR_TOO_MANY_RECORDS 

5902 

Too many records. 

MMIOERR_UNBUFFERED 

6001 

The specified file is not opened for 
buffered I/O. 

MMIOERR_CANN OTWRITE 

6002 

The buffer could not be written to 
disk. 

MMIOERR_CHUNKN OTFOUND 

6003 

The end of the file or parent 
chunk was reached. 

MMIOERR_INVALID_HANDLE 

6004 

The handle passed was not cor¬ 
rect. 

MMIOERR_INVALID_PARAMETER 

6005 

A parameter passed was not cor¬ 
rect. 

MMIOERR_INTERNAL_SYSTEM 

6006 

The operation failed due to an 
internal system error. 

MMIOERR_NO_CORE 

6007 

The system could not allocate the 
requested memory. 
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Error 

Number 

Description 

MMIOERR_INI_OPEN 

6008 

The system could not open the 
MMEMMIO.INI file. 

MMIOERR_INI_READ 

6009 

The system could not read the 
MMEMMIO.INI file. 

MMIOERR_INVALID_BUFFER_LENGTH 

6010 

The specified buffer length is 
invalid. 

MMIOERR_NO_BUFFER_ALLOCATED 

6011 

Write operation expected a buffer 
but none was allocated. 

MMIOERR_NO_FLUSH_FOR_MEM_FILE 

6012 

A flush was requested for a MEM 
file. 

MMIOERR_NO_FLUSH_NEEDED 

6013 

A flush was requested, but the 
buffer was not dirty. 

mmioerr_read_only_file 

6014 

The file was not opened in the 
WRITE mode. 

MMIOERR_WRITE_ONLY_FILE 

6015 

The file was not opened in the 
READ mode. 

MMIOERR_INSTALL_PROC_F AILED 

6016 

Installation of the I/O proc failed. 

mmioerr_read_failed 

6017 

System was unable to read, possi¬ 
ble hardware error. 

MMIOERR_WRITE_F AILED 

6018 

Writing a dirty buffer before read¬ 
ing has failed. 

MMIOERR_SEEK_F AILED 

6019 

System was unable to seek, possi¬ 
ble hardware error. 

MMIOERR_CANN OTEXPAND 

6020 

Unable to expand a MEM file for 
an advance request. 

MMIOERR_FREE_F AILED 

6021 

System was unable to free memo¬ 
ry it allocated. 

MMIOERR_EOF_SEEN 

6022 

The system has reached the end of 
file. 

MMIOERR_INVALID_ACCESS_FLAG 

6023 

The specified access flag is 
invalid. 
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Number 
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MMIOERR_INVALID_STRUCTURE 

6024 

The specified structure is invalid. 

MMIOERR_INVALID_SIZE 

6025 

The specified size is invalid. 

MMIOERR_INYALID_FILENAME 

6026 

The specified filename is invalid. 

MMIOERR_CF_DUPLICATE_SEEN 

6027 

System located a duplicate CTOC 
entry. 

MMIOERR_CF_ENTRY_NO_CORE 

6028 

System could not allocate memory 
for CTOC entry. 

MMIOERR_CF_WO_UNSUPPORTED 

6029 

RIFF compound files cannot be 
opened write-only. 

MMIOERR_CF_ELEMENTS_OPEN 

6030 

Compound file cannot be closed 
because elements are open. 

MMIOERR_CF_NON_BND_FILE 

6031 

The specified file is not a RIFF 
compound file. 

MMIOERR_CF_ENTRY_NOT_FOUND 

6032 

System failed to find requested 
CTOC entry. 

MMIOERR_DELETE_F AILED 

6033 

System failed to delete the 
requested file. 

MMIOERR_OUTOFMEMORY 

6034 

The advance operation requires a 
buffer. 

MMIOERR_INVALID_DLLNAME 

6035 

The specified DLL name is incor¬ 
rect. 

MMIOERR_EWALID_PROCEDURENAME 

6036 

The specified procedure is not 
valid for the DLL given. 

MMIOERR_MATCH_NOT_FOUND 

6037 

System could not locate a match 
in file entries. 

MMIOERR_SEEK_BEFORE_BEGINNING 

6038 

System cannot seek before begin¬ 
ning of file. 

MMIOERR_INVALID_FILE 

6039 

Invalid file given. 

MMIOERR_QOSUNAVAILABLE 

6040 

Quality of Service is unavailable. 





764 Developing Multimedia Applications Under OS/2 


Message 

Error 

Number 

Description 

MMIOERR_MEDIA_NOT_FOUND 

6041 

Media type not found on open. 

MMIOERR_ERROR_IN_FRAME_DATA 

6042 

The video frame data contains an 

error. 

MMIOERR_INVALID_DIM_ALIGN 

6043 

The video dimensions do not 
match the alignment. 

MMIOERR_CODEC_NOT_SUPPORTED 

6044 

The codec cannot be found. 

MMIOERR_UN SUPPORTED_FUN CTION 

6045 

Function not supported by the I/O 
procedure. 

MMIOERR_CLIPBRD_ERROR 

6046 

The clipboard cannot be accessed. 

MMIOERR_CLIPBRD_ACTIVE 

6047 

An active reference to data is 
already in clipboard. 

MMIOERR_CLIPBRD_EMPTY 

6048 

The clipboard does not contain 
compatible movie data or is 
empty. 

MMIOERR_NEED_NEW_FILENAME 

6049 

Another process has an active ref¬ 
erence to data in the file being 
saved. 

MMIOERR_INVALID_TRACK_OPERATION 

6050 

Invalid track operation requested. 

MMIOERR_INCOMPATIBLE_DATA 

6051 

The data in clipboard is not com¬ 
patible with data in open file. 

MMIOERR_ACCESS_DENIED 

6052 

Error accessing file. 

MMIOERR_MISSING_FLAG 

6053 

Flag missing for this message. 

MMIOERR_INVALID_ITEM_FLAG 

6054 

Invalid item flag specified. 




GLOSSARY 


This glossary includes terms and definitions from the following sources: 

• The American National Dictionary for Information Systems, ANSI X3.172- 
1990, copyright 1990 by the American National Standards Institute 
(ANSI). Copies may be purchased from the American National Standards 
Institute, 11 West 42 street, New York, New York 10036. Definitions are 
identified by the symbol (A) after the definition. 

• The Information Technology Vocabulary, developed by Subcommittee 1, 
Joint Technical Committee 1 of the International Organization for 
Standardization and the International Electrotechnical Commission 
(ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are 
identified by the symbol (I) after the definition; definitions from draft 
international standards, committee drafts, and working papers being 
developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the 
definition, indicating that final agreement has not yet been reached 
among the participating National Bodies of SCI. 

• MMPM/2 Programming Reference. 

• Multimedia Fundamental redbook. 

• Ultimedia Video IN Version 1.0 User’s Guide. 


access time— The time from issuing a command to read or write to a file on 
disk until the physical read or write is actually carried out. 

ADC —Analog-to-digital converter. 

ACPA —IBM Audio Capture and Playback Adapter. 
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adaptive differential pulse code modulation (ADPCM) —A bit-rate reduc¬ 
tion technique where the difference in pulse code modulation samples are not 
compressed before being stored. 

aliasing —When scanning an image, sloping or curved lines have a jagged 
appearance. The faster the scan, the more pronounced the effect. 

amp-mixer —A combination amplifier and mixer that is used to control the 
characteristics of an audio signal from one or more sources. Also referred to as 
an amplifier-mixer. 

amplifier —A device that increases the strength of input signals (either volt¬ 
age or current). Also referred to as an amp. 

amplitude —In music, this refers to the audio volume or loudness. 

analog —Pertaining to data consisting of continuously variable physical quan¬ 
tities. Contrast with digital. 

analog audio —Audio in which all information representing sounds is stored 
or transmitted in a continuous scale electrical signal, such as line level audio 
in stereo components. See also digital audio. 

analog signal— See analog audio. 

analog video —Video in which all the information representing images is in 
continuous-scale electrical signal for both amplitude and time. 

analog video overlay— See overlay. 

analog-to-digital converter (ADC) —A functional unit that converts data 
from an analog representation to a digital representations. (I) (A) 

Anti-aliasing —The process of reducing the visibility of jagged edges caused by 
aliasing. Achieved by filling in the areas between the points of the jagged edges 
with intermediate colors or shades of gray. 

Application Programming Interface (API) —A functional interface sup¬ 
plied by the operating system. 

application-supplied video window —An application can specify to 
MMPM/2 that it wants video played in a specific window (controlled by the 
application) instead of the default window (controlled by MMPM/2). Also 
referred to as an alternate video window. 

artifact —A product resulting from h support is handled by the control. 

aspect ratio —On a display screen, the ratio of the maximum length of a dis¬ 
play line to the maximum length of a display column. The ratio of height to 
width. (This term applies to areas or individual pels.) Refer to enhanced graph¬ 
ics adapter and video graphics adapter. 
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asymmetric video compression —In multimedia applications, the use of a 
powerful computer to compress a video for mastering so that a less powerful 
(less expensive) system is needed to decompress it. Contrast with symmetric 
video compression. 

audio track —A logical block of sequential audio data within a multimedia 
data file. 

AVI —Audio Video Interleaved; a digital video movie file format. For storing 
audio, video and other data within a file. This is a standard file format used to 
support software motion video. AVI files can contain multiple tracks of data. 
These data tracks can be interleaved to improve access times during playback 
of the file. 


balance —For audio, refers to the relative strength of the left and right chan¬ 
nels. A balance level of 0 is left channel only. A balance of 100 is right channel 
only. 

bitmap —A region of memory or storage that contains the pixels representing 
an image arranged in the sequence in which they are normally scanned to dis¬ 
play the image. A representation of an image by an array of bits. 

bit-block transfer —The transfer of a rectangular array of bitmap data. 

bitblt —Bit-block transfer. Synonym for blit. 

blit —Synonym for bitblt. 

blitting —To alter areas of a bitmap display quickly with a graphics image or 
pattern. 

BND file — A RIFF compound file. 

BND lOProc —An internal I/O procedure, provided by the MMPM/2 system, 
that supports the elements in a RIFF compound file. See also CF IOProc. 

brightness —Refers to the level of luminosity of the video signal. A brightness 
level of 0 produces a dark image. A brightness level of 100 produces a bright 
image. 

bundle file (BND) —A file that contains many individual files, called file ele¬ 
ments , bound together. The MMIO file manager provides services to locate, 
query, and access file elements in a bundle file. A RIFF compound file. 
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capture —To take a snapshot of motion video and retain it in memory. The 
video image may then be saved to a file or restored to the display. 

CF lOProc —An internal I/O procedure, provided by the MMPM/2 system, 
that supports RIFF compound files. The CF IOProc operates on the entire com¬ 
pound file (rather than on the elements in a RIFF compound file, as with the 
BND IOProc). The CF IOProc is limited to operations required by the system to 
ensure storage system transparency at the application level. See also BND 
IOProc. 

chunk —The basic building block of a RIFF file. A RIFF term for a formalized 
data area. There are different types of chunks, depending on the chunk ID. See 
junk chunk or RIFF chunk. 

chunk ID —A four-character code (FOURCC) that identifies the representa¬ 
tion of the chunk data. 

circular slider control —A knob-like control that performs like a control on a 
TV or stereo. 

CODEC —COmpressor/DECompressor (CODEC): an algorithm implemented 
either in hardware or software that can either compress or decompress a data 
object. For example, a CODEC can compress raw digital images into a smaller 
form so that they use less storage space. When used in the context of playing 
motion video, decompressors reconstruct the original image from the com¬ 
pressed data. This is dome at a high rate of speed to simulate motion. 

color palette —A set of colors that can be displayed on the screen at one time. 
This can be a standard set used for all images or a set that can be customized 
for each image. Synonym for CLUT. See also standard palette and custom 
palette. 

compact disc —An optical read-only disc for use with digital audio, data, 
video. 

compact disc, digital audio (CD-DA) —The specification for audio compact 
discs. See also Redbook audio. 

compact disc, read-only memory (CD-ROM) —High-capacity, read-only 
memory in the form of an optically read compact disc. 

compound device —A multimedia device model for hardware that requires 
additional data objects, referred to as data elements, before multimedia opera¬ 
tions can be performed. 
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compound file —A file that contains multiple file elements. Also see bundle 
file. 

compound file resource group (CGRP) —A RIFF chunk that contains all 
the compound file elements, concatenated together. 

compound file table of contents (CTOC)— A RIFF chunk that indexes the 
CGRP chunk, which contains the actual multimedia data elements. Each entry 
contains the name of, and other information about, the element, including the 
offset of the element within the CGRP chunk. All the CTOC entries of a table 
are of the same length and can be specified when the file is created. 

compression —A digital process that allows data to be stored or transmitted 
using less than the normal number of bits. Video compression refers to tech¬ 
niques that reduce the number of bits required to store or transmit images. 

compressor —A software program that uses an algorithm to compress images 
into a smaller form so they use less storage space. When used in the context of 
playing motion video, decompressors reconstruct the original image from the 
compressed data. This is done at a high rate of speed to simulate motion. 

connection— The establishment of the flow of information from a connector on 
one device to a compatible connector on another device. A connection can be 
made that is dependent on a physical connection, for example the attachment 
of a speaker to an audio adapter with a speaker wire. A connection can also be 
made that is completely internal to the PC, such as the connection between the 
waveaudio media device and the ampmix device. See also connector. 

connector— A software representation of the physical way in which multime¬ 
dia data moves from one device to another. A connector can have an external 
representation, such as a headphone jack on a CD-ROM player. A connector 
can also have an internal representation, such as the flow of digital informa¬ 
tion into an audio adapter. See also connection. 

content— A phrase used to the any sort of multimedia-related. Content can be 
the digitally recorded data for a sound, a bitmap of an image, a musical score, a 
video sequence for a movie, or even a combination of any of these together. 

contrast— The difference in brightness or color between a display image and 
the area in which it is displayed. A contrast level of 0 is minimum difference. A 
contrast level of 100 is maximum difference. 

cue point— A point that the system recognizes as a signal that may be acted 
upon. 

custom palette —A set of colors that is unique to one image or one applica¬ 
tion. See also standard palette and color palette. 
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D 


DAC —Digital-to-analog converter. 

data stream —All data transmitted through a data channel, 
data streaming —Real-time, continuous flowing of data. 

decode —To convert data by reversing the effect of previous encoding. To 
interpret a code. To convert encoded text into plain text by means of a code sys¬ 
tem. Contrast with encode. 

default video window —Refers to where video is displayed when an applica¬ 
tion does not indicate an application-defined window with the MCI_WINDOW 
message. This provided by and managed for the application by MMPM/2. See 
also application-defined window. 

default window —See default video window. 

delta frame —Refers to one or more frames occurring between reference 
frames in the output stream. Unlike a reference frame, which stores a complete 
image, a delta frame stores only the changes in the image from one frame to 
the next. See reference frame. 

destination rectangle —An abstract region which defines the size of an 
image to be created when recording images for software motion video playback. 
The ratio of this rectangle’s size to that of the source rectangle determines the 
scaling factor to be applied to the video. 

device capabilities —The functionality of a device, including supported com¬ 
ponent functions. 

device context —The device status and characteristics associated with an 
opened instance of a Media Control Interface device. 

device driver —A software program that controls a device attached to a com¬ 
puter, such as an input device. Under OS/2, a device driver is executed in the 
host processors privileged mode. 

device element —A data object, such as a file, utilized by a compound device. 

device sharing —The ability to share a device among many different applica¬ 
tions simultaneously. If a device is opened shareable, the device context will be 
saved by the operating system when going from one application to another 
application. Allowing a device context to be switched between Media Control 
Interface devices. 
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device-specific format —The storage or transmission format used by a 
device, especially if it is different from an accepted standard. 

digital —Pertaining to data in the form of numeric characters. Contrast with 
analog. 

digital audio —Material that can be heard that has been converted to digital 
form. Synonym for digitized audio. 

digital signal processor (DSP) —A high-speed co-processor designed to do 
real-time manipulation of signals. 

digital video —Video where all the information representing images is in com¬ 
puter data form. 

Digital Video Interactive (DVI) —A system for bringing full-screen, full- 
motion television pictures and sound to a regular PC. DVI is a chip set and 
uses delta compression; that is, only the image-to-image changes in each frame 
are saved rather than the whole frame. Data (video footage) is compressed into 
a form that reduces memory requirements by factors of 100 or greater. This 
compressed data is stored on optical discs and can be retrieved at a rate of 30 
frames per second. (The DVI technology was developed by RCA and then sold 
to Intel. IBM has chosen this technology for future use in the PS/2.) 

digitize —To convert an analog signal into digital format. An analog signal 
during conversion must be sampled at discrete points and quantized to discrete 
numbers. 

digitized image —An image derived from a scanning device or a digitizing 
card with a camera. 

digitizer —A device that converts to digital format any image captured by the 
camera. 

dither —The effect of blurring the colors of boundaries in color spread. 

dithering —When different pixels in an image are prebiased with a varying 
threshold to produce a more continuous gray scale despite a limited palette. 
This technique is used to soften a color line or shape. This technique also is 
used for alternating pixel colors to create the illusion of a third color. 

drop-frame time code —A nonsequential time code used to keep tape time 
code matched to real time. Must not be used in tapes intended for videodisc 
mastering. 
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dual plane video system —Refers to when graphics from the graphics 
adapter are separate from the analog video. That is, there is a separate graph¬ 
ics plane and video plane. The analog video appears behind the graphics, show¬ 
ing through only in the areas that are transparent. Since graphics and video 
are separate, capturing the graphics screen will only obtain graphics. 
Capturing the video screen will only obtain video. This is also true for restoring 
images. See also single plane video system. 

dynamic resource —A multimedia program unit of data that resides in sys¬ 
tem memory. Contrast with static resource. 

dynamic-link library (DLL) —A file that has the same format as an .EXE 
file and contains the actual dynamic-link run-time code. Contrast with LIB. 
See also dynamic linking. 


E 


element —A file or other stored data item. An individual file that is part of a 
RIFF compound-file. An element of a compound file also could be an entire 
RIFF file, a non-RIFF file, an arbitrary RIFF chunk, or arbitrary binary data. 
The particular resource within a subarea that is identified by an element 
address. 

encode —To convert data by the use of a code in such a manner that reconver¬ 
sion to the original form is possible. Contrast with decode. 

Extended Attributes — A feature of the OS/2 file systems which allows encap¬ 
sulation of information about a files’ ownership, content, and association along 
with that file. 


F 


fast threads —Threads created by an application that provide minimal 
process context, for example, just stack, register, and memory. With the 
reduced function, fast threads can be processed quickly. 

file element —An individual file that is part of a RIFF compound file. An ele¬ 
ment of a compound file can also be an entire RIFF file, a non-RIFF file, an 
arbitrary RIFF chunk, or arbitrary binary data. See media element. 
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file format—A language construct that specifies the representation, in charac¬ 
ter form, of data objects in a file. For example, MIDI, M-Motion, or AVC. 

file format handler —I/O procedure. Provides functions that operate on the 
media object of a particular data format. These functions include opening, 
reading, writing, seeking, and closing elements of a storage system. 

file format lOProc —An installable I/O procedure that is responsible for all 
technical knowledge of the format of a specific type of data, such as headers 
and data compression schemes. A file format IOProc manipulates multimedia 
data at the element level. A file format IOProc handles the element type it was 
written for and does not rely on any other file format IOProcs to do any pro¬ 
cessing. However, a file format IOProc might need to call a storage system 
IOProc to obtain data within a file containing multiple file elements. See 
IOProc. See also storage system IOProc. 

form type —A field in the first four bytes of the data field of a RIFF chunk. It 
is a four-character code identifying the format of the data stored in the file. A 
RIFF form is a chunk with a chunk ID or RIFF. For example, waveform audio 
files (WAVE files) have a form type of WAVE. 

FPS —Frames Per Second. The frame rate of a digital video movie is typically 
represented in this format. 

frame —One image in a sequential group of images. 

frame-step recording —Refers to the capturing of video and audio data frame 
by frame, from a computer-controlled, frame-steppable video source device, or a 
previously recorded AVI file. 

frame grabber —A device that digitizes video images. 

frame number —The number used to identify a frame. On videodisc, frames 
are numbered sequentially from 1 to 54,000 on each side and can be accessed 
individually; on videotape, the numbers area assigned by way of the SMPTE 
time code. 

frame rate (source) —Refers to the frame rate of the video source device. For 
a videodisc player, the speed at which frames are scanned is 30 frames a sec¬ 
ond for NTSC video, and 25 frames a second for PAL video. For most film, the 
speed is 24 frames a second. 

frame rate (output) —Refers to the frame rate of the movie file being record¬ 
ed. A target capture rate is set, but there is no guarantee that this rate will be 
maintained for real-time recording. Frames that are dropped are marked in 
the output file. During recording the percentage of frames that are dropped is 
displayed in the Status Area. 
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freeze —Disables updates to all or part of the video buffer. The last video dis¬ 
played remains visible. See also unfreeze. 

freeze-frame —A frame of a motion-picture film that is repeated so as to give 
the illusion of a still picture. 

full-frame time code —A standardized method, set by the Society of Motion 
Picture and Television Engineers (SMPTE), of address coding a videotape. It 
gives an accurate frame count rather than an accurate clock time. Synonym for 
nondrop time code. 

full-motion video —Video reproduction at 30 frames per second for NTSC sig¬ 
nals or 25 frames per second for PAL. 


G 


graphics overlay device —Refers to a video capture device that can superim¬ 
pose graphics or text on motion video or still video. 

graphics plane —In a dual plane video system, the graphics plane contains 
material drawn or generated by the graphics adapter. The graphics plane will 
be combined with the video plane to create an entire display image. 

greyscale —When video is displayed in shades of black and white. 

grouping —For Media Control Interface devices, refers to the ability to associ¬ 
ate dissimilar devices for a common purpose. Grouping MCI devices aids 
resource management by insuring that all devices in a group are kept together. 

H 


HMS —Hours-minutes-seconds. A time format for video disc players. 

HMSF —Hours-minutes-seconds-frames. A time format for videodisc players. 
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image —A still picture or one frame. 

image bitsperpel —Pertains to the number of colors supported by the current 
pel format. The currently accepted standard values are those supported by 
OS/2 bitmaps, for example, 1-, 4-, 8-, or 24-bits per pel. In addition, 12-bits per 
pel formats are accepted for YUV images (including the “y uv t>” pel format for 
RDIB files). 

image buffer —A location in memory where video images are stored for later 
use. 

image buffer formats —The format or representation of data buffers contain¬ 
ing video images. 

image compression —The method of compressing video image data to con¬ 
serve storage space. 

image file format —The format or representation of data files containing 
video images. 

image pelformat —Indicates the color representation that is to be used for 
images that are captured and saved. This normally includes palletized RGB, 
true-color RGB, or YUV color formats. 

image plane —In digital video display hardware that has more than one video 
memory array, each memory array is called an image plane. A number of 
planes may be displayed at one time. 

image quality —Represents the user’s or application’s subjective evaluation of 
complexity and quality of the image to be captured or saved. This setting is 
used to determine specific compression methods to use for saving the image. 

input/output control (IOCtl) —A system function that provides a method for 
an application to send device-specific control commands to a device driver. 

installable I/O procedure —A file format handler that provides functions 
that operate on the media object of a particular data format. These functions 
include opening, reading, writing, seeking, and closing elements. 

interlace —The technique of using more than one vertical scan to reproduce a 
complete image. In television a 2:1 interlace is used, giving two vertical scans 
per frame. One scan will be odd lines, the other will be even lines. 

interleave —To combine audio and video data in an alternating fashion so as 
to maximize synchronization between the two. 
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interleave ratio —The ratio of video to audio frames. 

interleaving —Refers to the arrangement of video and audio data in the AVI 
file, which enables efficient access of the data as bytes or streams during play¬ 
back. 

internal I/O procedure —An I/O procedure that is built into the MMPM/2 
system, including DOS, MEM, BND, and CF IOProcs. 

lOProc —A file format handler that provides functions that operate on the 
media object of a particular data format. These processes include opening, 
reading, writing, seeking, and closing elements of a storage system. There are 
two classes of I/O procedures: file format and storage system. 


j 


Joint Photographic Experts Group (JPEG) —A group that is working to 
establish a standard for compressing and storing still images in digital form. 
JPEG also refers to the standard under development by this group (JPEG 
standard). 


K 


key frames —The start and end frames of a single movement in an animation 
sequence; also can refer to the periodic full-frame images (key frames). 

kHz —Kilohertz, thousands of cycles per second. 


L 


latency —In video, the time it takes for the light from the phosphor screen to 
decay after the excitation is removed. Long-persistence phosphor has less flick¬ 
er of still images, but more blurring of moving images. 

LIST chunk —A chunk that contains a list or an ordered sequence of sub¬ 
chunks. 
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M-audio Capture and Playback Adapter (M-ACPA) —An adapter card (for 
use with the IBM PS/2 product line) that provides the ability to record and 
play back high quality sound. The adapter converts the audio input (analog) 
signals to a digital format that is compressed and stored for later use. 

M-control Program/2 —The software interface required for the M-Motion 
Video Adapter/A. It consists of APIs or toolkits for DOS, Windows, Windows 
MCI, OS/2, OS/2 MMPM/2. It also includes Pioneer and Sony videodisc player 
drivers for these environments. See also M-Motion Video Adapter /A. 

M-Motion —A multimedia platform that offers analog video in addition to 
quality sound and images. The M-Motion Video Adapter/A and the M-Control 
Program/2 master stream handler. 

MbMotion Video Adapter/a —A Micro Channel adapter that receives and 
processes signals from multiple video and audio sources, and then sends these 
signals to a monitor and speakers. Dual plane video hardware that offers ana¬ 
log video in addition to quality sound and images. The M-Motion Video 
Adapter/A requires the M-Control Program/2. 

media component — A processor of audiovisual information or media. Media 
components can be either internal or external physical devices or defined 
mechanisms for effecting higher-level function from internal hardware and 
software subsystems. An example is a waveform player component that uti¬ 
lizes the DSP subsystem and data streaming services to effect audio playback 
functions. 

media component capabilities —The functionality of a media component, 
including component functions that are supported. 

media component connection —A physical or logical link between media 
component connectors for a particular set of media component instances. 

media component connector —A physical or logical input or output on a 
media component. 

media component connector index —An identifier for a media component 
connector. 

media component control function —An operational function or action that 
a media component is capable of performing. For example, “record” is a control 
function that can be performed by a video tape recorder. 
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media component control function category —Any of several logical 
groupings of media component control functions. Component control functions 
are grouped in both functional and component-specific categories. 

media component driver —A software implementation or method that 
effects the function of a media component. For OS/2, a media component driver 
is a dynamic-link library (or set of libraries) that utilizes physical device dri¬ 
vers, MCI services, and OS/2 to implement the function of the media 
component. 

media component ID —Media component identification. A unique identifier 
for a component. 

media component instance —A case of an application’s use of a media com¬ 
ponent. 

media component manager (MCD) —The application interface level of MCI 
that presents a consistent API for controlling media components, managing 
component connections, and handling component resource sharing and 
contention. 

media component type —A class of media components that exhibit similar 
behavior and capabilities. Examples of media component types are analog 
video display hardware and MIDI synthesizers. 

Media Control Interface (MCI) —A generalized interface to control multime¬ 
dia devices. Each device has its own MCI driver that implements a standard 
set of MCI functions. In addition, each media driver can implement functions 
that are specific to the particular device. 

media device manager (MDM) —A system service that, when two or more 
applications attempt to control a media device, determines which process gains 
access. 

media driver —A device driver for a multimedia device. See also device driver. 
A software implementation or method that effects the function of a media 
device. 

memory file —A block of memory that is perceived as a file by an application. 

memory playlist —A data structure in the application used to specify the 
memory addresses to play from or record to. The application can modify the 
playlist to achieve various effects in controlling the memory stream. 

millisecond —One thousandth of a second. 

minutes-seconds-frames (MSF) —A time format based on the 75-frames-per- 
second CD digital audio standard. 
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MMIO file services —System services that enable an application to access 
and manipulate multimedia data files. 

MMIO manager —Multimedia input/output manager. The MMIO manager 
provides services to find, query, and access multimedia data objects. It also 
supports the functions of memory allocation and file compaction. The MMIO 
manager uses IOProcs to direct the input and output associated with reading 
from and writing to different types of storage systems of file formats. 

MMTIME —Standard time and media position format supported by the media 
control interface. This time unit is 1/3000 second, or 333 microseconds. 

monitor window —A graphical window, available from a digital video device, 
which displays the source rectangle, and any subset of this video capture 
region. See destination rectangle for related information. 

motion video capture adapter —An adapter that, when attached to a com¬ 
puter, allows an ordinary television picture to be displayed on all or part of the 
screen, mixing high-resolution computer graphics with video; also enables a 
video camera to become an input device. 

Moving Pictures Experts Group (MPEG) —A group that is working to 
establish a standard for compressing and storing motion video and animation 
in digital form. 

MSF —Minutes-seconds-frames. 

multimedia —Material presented in a combination of text, graphics, video, 
image, animation, and sound. 

multimedia input/output (MMIO) —System services that provide a variety 
of functions for media file access and manipulation. A consistent programming 
interface where an application, media driver, or stream handler can refer to 
multimedia files, read and write data to the files, and query the contents of the 
files, while remaining independent of the underlying file formats or the storage 
systems that contain the files. 

multitasking —A technique which allows several processes to appear to run 
simultaneously, even though the computer only has one CPU. This is achieved 
by sequentially switching the CPU between tasks. 

Musical Instrument Digital Interface (MIDI) —A protocol that allows a 
synthesizer to send signals to another synthesizer or to a computer, or a com¬ 
puter to a musical instrument, or a computer to another computer. 

mute —To temporarily turn off the audio for the associated medium. 
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National Television Standard Committee (NTSC) —A committee that set 
the standard for color television broadcasting and video in the United States 
(currently in use also in Japan); also refers to the standard set by this commit¬ 
tee (NTSC standard). 

non-streaming device —A device that contains both source and destination 
information for multimedia. A device that transmits data (usually analog) 
directly, without streaming to system memory. 

Nyquist, H. —Early researcher in the area of audio theory. His research in 
the 1920s resulted in Nyquist’s Theory. 

Nyquists Theory —A theorem that proposes that if samples of an analog 
audio signal are taken at twice the rate of the highest frequency being record¬ 
ed, sufficient information will be acquired to faithfully reproduce the original, 
digitally. 


o 


object —Anything that exists in and occupies space in storage and on which 
operations can be performed; for example, programs, files, libraries, and fold¬ 
ers. Anything to which access is controlled; for example, a file, a program, an 
area of main storage. See also data object and media object. Anything a user 
can manipulate as a single unit; icons and files are examples of objects. 

overlay —The ability to superimpose text and graphics over video. 

overlay device —Provides support for video overlaying along with video 
attribute elements. The video overlaying handles tasks such as displaying, and 
sizing video. Synonym for video overlay device. 

p 


palette— See color palette, standard palette, and custom palette. 

panning —The process of focusing the direction of audio playback or recording, 
from one signal source to another. Commonly used to create the feeling of 
motion in an audio recording. 
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pel —An acronym derived from the words “picture element” that is used when 
the associated numerical value is binary, that is, 0 or 1. See also pixel. 

Phase Alternation Line (PAL) —Television broadcast standard for European 
video outside of France and the Soviet Union. 

physical device driver (PDD) —A program that handles hardware inter¬ 
rupts and supports a set of input and output functions. 

picture element —In computer graphics, the smallest element of a display 
surface that can be independently assigned color and intensity. 

pixel —A single point of an image, having a single pixel value. 

pixel value —A number, or series of numbers, which represent the color and 
luminance of a single pixel. 

playback window —The graphic window in which software motion video is 
displayed. This window can be supplied by an application, or a default window 
can be created by a digital video device. 

preroll —The process of preparing a device to begin a playback or recording 
function with minimal latency. During a multimedia sequence, it might require 
that two devices be cued (prerolled) to start playing and recording at the same 
time. 

primary window —A window in which the main interaction between a user 
and an object takes place. 

Proc —A custom procedure, called by the particular utility manager, to handle 
input or output to files of a format different from DOS, MEM, or BND; for 
example, AVC or TIFF. By installing custom procedures, existing applications 
no longer need to store multiple copies of the same media file for running on 
various platforms using different file formats. See also static resource and 
dynamic resource. 

pulse code modulation (PCM) —In data communication, variation of a digi¬ 
tal signal to represent information. Also referred to as Linear PCM. 

push button —A graphical control, labeled with text, graphics, or both, that 
represents an action that will be initiated when a user selects it. For example, 
when a user clicks on a Play button, a media object begins playing. 



782 


Developing Multimedia Applications Under OS/2 


R 


raster graphics —Computer graphics in which a display image is composed of 
an array of pels arranged in rows and columns. 

real-time recording —Refers to the capturing of video and audio data in real 
time, as the analog signals are generated from the video source device. The 
video source device can be a camcorder, videotape, or videodisc player. 

real time —Pertains to the processing of data by a computer in connection 
with another process outside the computer according to time requirements 
imposed by the outside process. This term is also used to describe systems 
operating in conversational mode and processes that can be influenced by 
human intervention while they are in progress. A process control system, or a 
computer-assisted instruction program, in which response to input is fast 
enough to affect subsequent output. 

record —To transfer data from one source or set of sources to another medium 
(such as microphone, CD, videodisc). 

reference frame —Refers to the complete frame that is created at periodic 
intervals in the output stream. An editing operation always begins at a refer¬ 
ence frame. Synonymous with key frame and I-frame. See delta frame. 

reference frame interval —Frequency with which reference frames are to be 
inserted in the output data stream. 

resolution —The ability of an image reproducing system to reproduce fine 
detail. In television, resolution is specified in lines per picture height. 

resource interchange file format (RIFF) —A tagged file format framework 
intended to be the basis for defining new file formats. 

RGB —Red, Green, Blue. This is a format for representing the color of a pixel. 

RGB5-6-5 —An image format in which each pixel is represented as 16-bits. The 
high-order 5-bits is red, the next 6-bits are green and the low-order 5-bits are 
blue. 

RIFF chunk —A chunk with a chunk ID of RIFF. In a RIFF file, this must be 
the first chunk. 

RIFF compound file —A file containing multiple file elements, or one file ele¬ 
ment that makes up the entire RIFF file. The MMIO manager provides ser¬ 
vices to find, query, and access any file elements in a RIFF compound file. 
Synonym for bundle file. 
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Sampling— The process of acquiring data from some source. Commonly used 
to refer to the process of recording audio in a digital form. 

S-video —Separated video or super video. A signal system using a Y/C format. 
See also Y/C, composite video, and component video. 

S-video input connector —A special connector that separates the chromi¬ 
nance from the luminance signal. 

skew— The number of frames that the audio stream leads the video stream in 
the AVI file. 

secondary window— A window that contains information that is dependent 
on information in a primary window and is used to supplement the interaction 
in the primary window. 

secondary window manager —A sizable dialog manager that enables appli¬ 
cation writers to use CUA-defined secondary windows instead of dialog boxes. 

sequencing —The process of MIDI musical composition whereby the MIDI 
messages are ordered to produce the effect to any given musical score or 
arrangement. 

sequencer —The name of the logical MIDI device in MMPM/2. 

simple device —A multimedia device model for hardware which does not 
require any additional objects, known as device elements, to perform multime¬ 
dia functions. 

single plane video system —Refers to combining video and graphics into one 
buffer. This may appear the same as a dual plane video system, but since all 
the data is in one buffer, captured and restore operations will obtain both 
graphics and video components in one operation. See also dual plane video 
system. 

slave stream —A stream that is dependent upon the master stream to main¬ 
tain synchronization. 

slave stream handler —In SPI, regularly updates the sync pulse EVCB with 
the stream time. The Sync/Stream Manager checks the slave stream handler 
time against the master stream time to determine whether to send a sync 
pulse to the slave stream handler. 

slider— A visual component of a user interface that represents a quantity and 
its relationship to the range of possible values for that quantity. A user can 
also change the value of the quantity. Sliders are used for volume and time 
control. 
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SMPTE —Society of Motion Picture and Television Engineers. Usually refers 
to a time code based on a 24 hour clock, and frames added to the MIDI data 
stream to synchronize music to film or television frames. 

SMPTE time code —A frame-numbering system developed by SMPTE that 
assigns a number to each frame of video. The 8-digit code is in the form 
HH:MM:SS:FF (hours, minutes, seconds, frame number). The numbers track 
elapsed hours, minutes, seconds, and frames from any chosen point. 

source rectangle —An abstract region representing the area available for use 
by a video capture adapter. This window is displayed in the monitor window of 
the digital video device. A subset of the maximum possible region to be cap¬ 
tured can be defined; such a subset is shown by an animated dashed rectangle 
in the monitor window. 

source window —See source rectangle. 

split streaming —A mechanism provided by the Sync/Stream Manager to cre¬ 
ate one data stream source with multiple targets. 

standard palette —A set of colors that is common between applications or 
images. See also custom palette and color palette. 

static resource —A resource that resides on any read-and-write or read-only 
medium. Contrast with dynamic resource. 

still — A static photograph. 

storage system —The method or format a functional unit uses to retain or 
retrieve data placed within the unit. 

storage system lOProc —A procedure that unwraps data objects such as 
RIFF files, RIFF compound files, and AVC files. IOProcs are ignorant of the 
content of the data they contain. A storage system IOProc goes directly to the 
OS/2 file system (or to memory in the case of a MEM file) and does not pass 
information to any other file format or storage system IOProc. The internal I/O 
procedures provided for DOS files, memory files, and RIFF compound files are 
examples of storage system IOProcs, because they operate on the storage 
mechanism rather than on the data itself. See also file format IOProc. 

stream —To send data from source to destination via buffered system memory. 

stream handler —A routine that controls a program’s reaction to a specific 
external event through a continuous string of individual data values. 

stream manager —A system service that controls the registration and activi¬ 
ties of all stream handlers. 
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stream protocol control block (SPCB) —The system service that controls 
the behavior of a specified stream type. This enables you to subclass a stream’s 
data type, change data buffering characteristics, and alter synchronization 
behavior and other stream events. 

string commands— See command string interface. 

subchunk —The first chunk in a RIFF file is a RIFF chunk ; all other chunks 
in the file are subchunks of the RIFF chunk. 

symmetric video compression —A technology in which the computer can be 
used to create, as well as play back, full-motion, full-color video. 

sync —Synchronization or synchronized. 

sync group —A master stream and all its slaves that can be started, stopped, 
and searched as a group by using the slaves flag on each of the following SPI 
functions: 

° SpiStartStream 

• SpiStopStream 

• SpiSeekStream 

sync pulse —A system service that enables each slave stream handler to 
adjust the activity of that stream so that synchronization can be maintained. 
Sync pulses are introduced by transmission equipment into the receiving 
equipment to keep the two equipments operating in step. 

synchronization —The action of forcing certain points in the execution 
sequences of two or more asynchronous procedures to coincide in time. 

synchronous —Pertaining to two or more processes that depend upon the 
occurrence of specific events such as common timing signals. 

synthesizer —A musical instrument that allows its user to produce and con¬ 
trol electronically generated sounds. 

SVGA —Super Video Graphics Adapter/Array. 


tagged image file format (TIFF) —An easily transportable image file type 
used by a wide range of multimedia software. 

tearing —Refers to when video is displaced horizontally. This may be caused 
by sync problems. 
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tempo— the speed or rate of which a musical score is replayed. 

TMSF —A time format expressed in tracks, minutes, seconds, and frames, 
which is used primarily by compact disc audio devices. 

track —A path associated with a single Read/Write head as the data medium 
moves past it. 

transform —In data compression, it refers to a process which converts a block 
of data into an alternate form. 

transform device —A device that modifies a signal or stream received from a 
transport device. Examples are amplifier-mixer and overlay devices. 

transparency— When a selected color on a graphics screen is made transpar¬ 
ent to allow the video “behind it” to become visible. Often found in dual plane 
video subsystems. 

transparent color— Video information is considered as being present on the 
video plane which is maintained behind the graphics plane. When an area on 
the graphics plane is painted with a transparent color, the video plane is made 
visible. See also dual plane video system. 


u 


Ultimotion— An IBM video-compression algorithm optimized for software 
playback on a general-purpose microprocessor. 

underrun— Loss of data caused by the inability of a transmitting device or 
channel to provide data to the communication control logic (SDLC or BSC/SS) 
at a rate fast enough for the attached data link or loop. 

user-defined message — A private message sent directly to an I/O procedure 
by using the mmioSendMessage function. All messages begin with an 
MMIOM prefix, with user-defined messages starting at MMIOM_USER or 
above. 

U,V —The Chrominance components of a PAL color television system. 
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VGA—IBM Video Capture Adapter. This is the IBM video capture adapter. 

vertical resolution —The specification of resolution in the vertical direction, 
meaning the ability to reproduce closely-spaced horizontal lines. 

VHS —Very high speed. A consumer and industrial tape format (VHS format). 

video —Pertains to the portion of recorded information that can be seen. 

video attribute control —Provides access to and operation of the standard 
video attributes: brightness, contrast, freeze, hue, saturation, and sharpness. 
All device communication and user interface support is handled by the control. 

video attributes —Refers to the standard video attributes: brightness, con¬ 
trast, freeze, hue, saturation, and sharpness. 

video display buffer —The buffer containing the visual information to be dis¬ 
played. This buffer is read by the video display controller. 

video graphics adapter —A graphics controller for color displays. The pel 
resolution of the video graphics adapter is 4:4. 

video image —A still video image that has been captured. Synonymous with 
image and still image. 

video monitor —A display capable of accepting a video signal that is not mod¬ 
ulated for broadcast either on cable or over the air; in videotaping, a television 
screen located away from the set where the footage can be viewed as it is being 
recorded. 

video plane —In dual plane video system, the video plane contains the video. 
This video plane will be combined with the graphics plane to create an entire 
display image. 

video quality —The compression quality level setting to be set for the 
CODEC. This value is in the range of 0 (minimum) - 100 (maximum). 

video record rate —Frame rate for recording, as an integral number of 
frames per second. This sets the target capture rate, but there are no assur¬ 
ances this rate will be attained. Drop frame records will be inserted into the 
output data stream to indicate frames dropped during the capture/record 
process. 

video record frame duration —Frame rate for recording as the time dura¬ 
tion of each frame in microseconds. Useful for setting non-integer frame rates, 
for example, 12.5 FPS of a PAL videodisc: 1000000/12.5 = 8000 microseconds. 
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VSD —Vendor Specific Driver. 

video scaling —Expanding or reducing video information in size or area. See 
also aspect ratio. 

video windows —Graphical PM-style windows in which video is displayed. 
Most often associated with the video overlay device. 

videodisc —A disc on which programs have been recorded for playback on a 
computer or a television set; a recording on a videodisc. The most common for¬ 
mat in the United States and Japan is an NTSC signal recorded on the optical 
reflective format. 

videodisc player control —Provides access to and operation of the following 
videodisc functions: eject, pause, play forward, play reverse, position, record, 
repeat, rewind, scan forward, scan reverse, step forward, step reverse, and 
stop. All device communication and user interface or more audio sources. Also 
referred to as an amplifier-mixer. 

volume —The intensity of sound. A volume of 0 is minimum volume. A volume 
of 100 is maximum volume. 


w 


waveform —The digital representation of audio (sound waves). 

window —An area of the screen with visible boundaries through which panel 
information is displayed. 

window coordinates —The size and location of a window. 

WPS— Workplace Shell. 


XGA —extended Graphics Array adapter. This is the IBM PS/2 standard video 
adapter technology. 

XGA2 —The second XGA. It provides 64K colors at 640x480 resolution. 
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Y —In color video, the abbreviation for luminance. 

Y/C —Color image encoding that separates luminance (Y) and chrominance© 
signals. 

YXJV —Color image encoding scheme that separates luminance (y) and two 
color signals: red minus Y (U), and blue minus Y (V). Transmission of YUV can 
take advantage of the eye’s greater sensitivity to luminance detail than color 
tail. 

yuv4-l-l— An image format in which each pixel is represented as 16-bits. Each 
pixel has a unique luminance value, and 4 pixel horizontally arrayed share the 
same chrominance. 
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A 


acquire command, 48-49 

for waveaudio devices, 186-87 
ADSH (Audio Stream Handler), 
182, 183 

aliases for device names, 40-41 
alignment keyword, with set 
command, 255 

ampmix devices, 183, 190, 204-5, 
205, 214, 215 
with digital video devices, 
241-43 

video playback and, 229 
analog signal, 175-76 
animated buttons, 304 
animation, 270 

AssociateCodec routine, 141-146 
asynchronous mode, 26 
asynchronous with notification 
command execution mode, 

43-44 

asynchronous without notification 
command execution mode, 43 
audio. See waveaudio 
audio adapters, 363-64 
audio all keyword combination, 
with set command, 255 


audio connections, 214-217 
audio file formats, 111 
translation of, 117 
audio files, editing, 190-92 
audio left keyword combination, 
with set command, 255 
audio over keyword combination, 
with set command, 255 
audio right keyword combination, 
with set command, 255 
audio standard presentation 
header, 111 

Audio Stream Handler. See ADSH 
(Audio Stream Handler) 
audiosync direction keyword 
combination, with status 
command, 251 

audiosync forward command, 265 
audiosync forward keyword combi¬ 
nation, with set command, 254 
audiosync keyword 

with set command, 254 
with status command, 251 
audiosync reverse command, 265 
audio volume keyword combina¬ 
tion, with set command, 256 
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audioxync reverse keyword combi¬ 
nation, with set command, 254 
AVG_DATA_RATE parameter, 157 
AVI movie file format, 101, 120 
AVI movies, playing, 247-48 

B 


balance, 177 
basic command, 5-6 
bitspersample keyword combination, 
with set command, 256 
bitspersecond keyword, with status 
command, 253 

BPS (bits per second), 177-78 
BRANCH_OPERATION command, 
67, 70, 217, 222-223 
brightness keyword 
with set command, 256 
with status command, 253 
buffered I/O operations, 107-8 
bundled files, 102, 150. 

See also compound files 

c 


CALL_OPERATION command, 67, 
217, 223 

capability command, 49-50, 234 
with digital video devices, 238-41 
for waveaudio devices, 188-90 
CD audio devices, 5, 20 
CD digital audio (compact disc audio; 
CD/DA discs), 287-98 
cuepoints and positionadvise 
messages, 294 


DAC vs. streaming modes, 288-91 
data, 287-88 
table of contents, 295-96 
CD-ROM drives, 287-89, 330 

single-spin vs. multi-spin, 322-23 
supported by OS/2 and MMPM/2, 
371-72 

volume settings for, 293-94 
channels keyword 

with set command, 256 
with status command, 253 
chunk ID, 102 

circular sliders, 24, 300, 305-6, 312-13 
clipboard, editing commands and, 
51-53 

clipboard keyword, with status 
command, 251 
close command 

with digital video devices, 238 
for waveaudio devices, 207 
CODECASSOC structure, 141 
CODECINIFILEINFO data structure, 
163, 164 

CODEC procedures, 20-21, 73, 161-72 
installing, 164-65 
loading, 165 
messages for, 165-66 
querying, 167-72 
CODECs (compressors and 
decompressors) 
access messages, 146 
associating with file format I/O 
procedures, 140-46 
digital video, 163, 267-70 
types of, 163 
for video capture, 282-83 
coding an application, 339-45 
color depth, 225 
color space scalability, 233 
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compact disc audio 
See CD digital audio 
compound devices, 5 
compound files, 150-56 
APIs for, 151-52 
creating, 152-54 
querying entries in, 154-56 
connection command, 59-60 
connections, audio, 214-17 
connector command, with digital video 
devices, 243 

connectorinfo command, 60-61 
contrast keyword 

with set command, 256 
with status command, 253 
control messages, for graphic buttons, 
303-4 

controls, multimedia, 8-9 
convert keyword 

with cut, copy and paste 
commands, 209 
with paste command, 53 
copy command, 52 
for movies, 260 
for recordings, 208, 209 
C programming language, 11 
CSM_QUERYIN CREMENT 
message, 306 

CSM_QUERYRADIUS message, 306 
CSM_QUERYRANGE message, 306 
CSM_SETBITMAPDATA 
message, 306 

CSM_SETINCREMENT message, 306 
CSM_SETRANGE message, 306 
CSM_SETVALUE message, 306 
CSN_CHANGED message, 306 
CSN_QUERYBACKGROUNDOLOR 
message, 306 

CSN_SETFOCUS message, 306 


CSN_TRACKING message, 306 
CSS_360, 305 
CSS_MIDPOINT, 305 
CSS_NOBUTTON, 305 
CSS_NONUMBER, 305 
CSS_NOTEXT, 305 
CSS_POINTSELECT, 305 
CSS_PROPORTIONALTICKS, 306 
cue command 

for digital video capture devices, 
277-79 

for digital video devices, 244-45 
prerolling devices with, 317 
for waveaudio devices, 192 
CUEPOINT_OPERATION command, 
68, 69-70, 217, 221 
cuepoints, 66 

for CD audio, 294 
with digital video devices, 250-51 
current track keyword combination, 
with status command, 251 
cut command, 52, 53 
for movies, 261 
for recordings, 208, 209 

D 


DAC (digital to analog converter), 
288-91 

DATA_OPERATION command, 68, 
217, 220 

data translation, 115-20 
decompression algorithms, 226-27 
defaultconnection command, 61 
default window, 258-59 
delete command, 52, 53 
for movies, 261 
for recordings, 210-11 
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delta frame, 249 
developtment tools, 373-77 
device IDs, for waveaudio devices, 
187-88 

device names and aliases, 40-41 
device-specific commands, 5-6 
dialogs, 333-35 
digital video 
editing, 230 
on OS/2, 227-28 
overview of, 225-27 
playing back, 231-32 
scalability, 232-33 
digital video capture, 271-85 
adapters supported, 365-71 
architecture of, 272-80 

cueing a digitalvideo device for 
input, 277-79 

loading digital video capture 
devices, 274-75 
monitoring a capture, 276-77 
non-real-time (off-line) capture, 
272, 279-80 

opening digital video capture 
devices, 274 

real-time capture, 272-79 
setting digitalvideo device 
capture attributes, 275-76 
compression CODECs for, 282-83 
hardware requirements, 281-82 
image related commands, 283 
IOCTL and VSD interfaces, 284-85 
TV signal, 283-84 
digital video CODECs, 163, 230, 
267-70 

digital video devices, 227-28 
capturing video and. See digital 
video capture 

editing operations with, 230 


interface for, 233-67 

audio device connection for movie 
playback, 241-43 
AVI movies creates on other 
operating systems, 247-48 
capability command, 238-41 
capture device commands, 235 
commands available for, 234-35 
cue command, 244-45 
display window and window 
management commands, 
258-60 

DIVE (Direct Video Interface 
Extensions), 265-67 
editing operations, 260-63 
opening the digital video and 
loading a movie, 235-38 
overlay device commands, 235 
play command, 245-46 
querying device status, 251-54 
querying digital video, 243 
seeking a movie, 249-50 
setting cuepoints and position 
advise events, 250-51 
setting device controls and 
attributes, 254-57 
step command, 246 
stopping, pausing and resuming 
a movie, 248 

synchronization audio and video, 
263-65 

playback architecture of, 228-33 
play operations with, 231-32 
digital waveaudio. See waveaudio 
(waveform audio) 

diskette provided with this book, 362 
DIVE (Direct Video Interface 
Extensions), 265-67 
DiveAllocImageBuffer API, 266 
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DiveAquireFrameBuffer API, 266 
DiveBeginlmageBufferAccess API, 
266 

DiveBlitlmage API, 267 
DiveCalcFrameBufferAddress API, 
267 

DiveClose API, 267 
DiveDeacquireFrameBuffer API, 267 
DiveEndlmageBufferAccess API, 267 
DiveFreelmageBuffer API, 267 
DiveOpen API, 267 
DiveQueryCaps API, 267 
DiveSetDestinationPalette API, 267 
DiveSetupBlitter API, 267 
DiveSwitchBank API, 267 
DLLs (dynamic link libraries), 29 
DosSetRelMaxFH API, 321-22 
DOS storage system, 149-150 
droppedframepct keyword combina¬ 
tion, with status command, 251 
dropped frames, 264 
DVI/Action Media II, 375-76 

E 


editing, 146-48 

with digital video devices, 230 
movies, 260-63 
recordings, 208-11 
editing commands, 51-53 
exclusive instance keywords, opening 
waveaudio devices with, 187 
exclusive instance sharing state, 

47-48 

exclusive sharing state, 47-49 
EXIT_OPERATION command, 68, 217 


F 


fast keyword, with play command, 245 
FAT file system, 149 
file format I/O procedures, 72-73, 
98-121 

associating CODEC procedures 
with, 140-46 
buffering, 107-8 
data translation, 115-20 
editing operations, 146-48 
file formats available for, 102 
format independent file headers, 
108-15 

messages expected to be supported 
by, 99-101 

with multiple track files. 

See multiple track files 
opening files, 104-105 
opening memory files, 106-7 
reading and writing, 136-37 
for RIFF files, 101-2 
file handles, 321-22 
file names, device names as, 40 
File System Stream Handler. See 
FSSH (File System Stream 
Handler) 

FLI/FLC Animation, 270 
format tag keyword combination 
with set command, 256 
with status command, 253 
format tags, recording audio 
and, 202-4 

forward keyword, with status 
command, 252 
FOURCCs, 80-82, 85-86 
fps keyword, with set command, 255 
frame rate, 225 



796 Developing Multimedia Applications Under OS/2 


scalability of, 232-33 
FSSH (File System Stream Handler), 
182,183 

fully shareable state, 47 

G 


gain, setting, 204-5 
GBM_ANIMATE message, 303 
GBM_QUERYANIMATIONACTIVE 
message, 303 

GBM_QUERYANIMATIONRATE 
message, 303 

GBM_QUERYBITMAPINDEX 
message, 304 

GBM_QUERYSTATE message, 303 
GBM_QUERYTEXTPOSITION 
message, 304 

GBM_SETAMMATIONRATE 
message, 303 

GBM_SETBITMAPINDEX message, 

303 

GBM_SETGRAPHICDATA message, 

304 

GBM_SETSTATE message, 303 
GBM_SETTEXTPOSITION message, 
304 

GBN_BUTTONDOWN message, 303 
GBNJBUTTONHILITE message, 303 
GBNJ3UTTONUP message, 303 
GBS_ANIMATION flag, 301 
GBS_AUTOANIMATION flag, 301 
GBS_AUTOTWOSTATE flag, 302 
GBS_DISABLEBITMAP flag, 302 
GBS_3D_TEXTRAISED flag, 302 
GBS_3D_TEXTRECESSED flag, 302 
GBS_HILITEBITMAP flag, 302 
GBS_TWOSTATE flag, 302 


graphic buttons, 24, 300-304 
animated, 304 
control messages for, 303-4 
owner notifications and, 302-3 
styles of, 301-2 
two-state, 304-5 
group command, 61-62 

H 


header files, 28 
headers 

of multiple track files, 120-27 
presentation, 108-15 
HMMIO, 74, 77-78 
horizontal image extent keyword 
combination, with status 
command, 252 

horizontal video extent keyword 
combination, with status 
command, 252 
HPFS file system, 149 
hue keyword 

with set command, 256 
with status command, 253 

I 


Icon Author by AimTech, 373-74 
IDE devices, 327-29 
IFF (Interchange File Format), 6 
I-frame interval, 249 
I-frames, 249 

image bitsperpel keyword combina¬ 
tion, with status command, 254 
image file formats, 111 
translation of, 117-18 
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image pelformat keyword combina¬ 
tion, with status command, 254 

image standard presentation 
header, 110 

Indeo, compression and decompres¬ 
sion with, 269 

info command, with digital video 
devices, 243-44 

interrupt driven device drivers, 
329-30 

IOCTL interface, 284-85 

I/O procedures, 20, 21, 72-77, 79-97. 
See also CODEC procedures; file 
format I / O procedures; storage 
system I/O procedures 
child, 76 

format information about, 92-93 
FOURCCs for, 80-82 
identification of, 81-83 
installation of, 83-92 
media types of, 79-80 
types of, 79 

L 


laserdisc devices supported by 
MMPM/2, 372-73 
length keyword, with status 
command, 252 

length track keyword combination, 
with status command, 252 
Linear PCM, 178 
load command, 6 

for digital video capture 
devices, 274-75 

with digital video devices, 236 
for waveaudio devices, 190-92 


LOOP_OPERATION command, 68, 
70, 217, 222 

M 


masteraudio command, 58-59 
MAX_DATA_RATE parameter, 157 
MAX_EE_JITTER parameter, 157 
MCD (Media Control Device), 34 
MCDs (Media Control Drivers), 

18-19, 21 
MCI++, 373 

MCI (Media Control Interface), 5, 
17-19, 26, 31-70 
capability command in, 49-50 
command execution mode, 43-46 
device names and aliases and, 40-41 
editing commands in, 51-53 
mciSendString and 

mciSendCommand APIs, 31-36 
programming tips, 315-20 
cue command for prerolling 
devices, 317 

detecting if MMPM/2 is installed 
on a system, 315-16 
loading and reloading, 319 
opening with a data element vs. 
opening and then loading a 
file, 319 

optimizing use of set command 
for audio devices, 319-20 
setcuepoint command, 318 
setpositionadvise command 
frequency, 317-18 
setting and querying MMPM/2 
workpath, 318 
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string interface vs. procedural 
interface, 316 

wait vs. notify keyword or flag, 
316 

resource management and, 46-49 
REXX programming interfaces for, 
37-39 

status command in, 50-51 
system commands in, 54-62 
connection, 59-60 
connectorinfo, 60-61 
defaultconnection, 61 
group, 61-62 
masteraudio, 58-59 
sysinfo, 54, 58 
system values in, 63-70 
memory playlist, 67-70 
querying, 64 

synchronization for movie files, 
64-66 

MCI_CAPTURE command, 283 
MCIERR_INVALID_BUFFER, 296 
MCIERR_OUTOFRANGE, 63 
mciGetDevicelD API, 38 
mciGetErrorString API, 38, 63 
MCI_GETIMAGEBUFFER command, 
235, 283 

MCI_GETTOC command, 295-97 
MCI_NOTIFY_ABORTED, 44-46 
MCI_NOTIFY_SUCCESSFUL, 44 
MCI_NOTIFY_SUPERSEDED, 44-46 
MCI_OPEN command, 18 
MCI_OPEN_MMIO flag, 43 
MCI_PLAY command, 35 
mciPlayFile API, 199-200 
mciPlayResource API, 199 
mciQuerySysValue API, 64 
mciRecordAudioFile API, 200 
mciRxGetDevicelD, 38, 39 


mciRxGetErrorString, 38, 39 
mciRxSendString, 38, 39 
mciSendCommand API, 26, 31, 34, 
35,42 

for audio playback and 
recording, 181 
error codes returned by, 63 
syntax of, 31-32 

mciSendString API, 26, 31, 35, 36, 
38, 42 

for audio playback and 
recording, 181 
syntax of, 33-34 
MCISTRNG, 29 
MCI_SYSINFO message, 40 
MDM (Media Device Manager), 17, 
18, 34 

device names and aliases and, 40 
media present keyword combination, 
with status command, 252 
MediaSCRIPT OS/2 by Network 
Technology Corporation, 374 
media types, of I/O procedures, 79-80 
memory files, opening, 106-107 
memory playlist, 67-70 
memory usage, running multiple 
multimedia applications and, 
323-25 

MEM storage system, 149-150 
menus, 335-36 
message command, 50 
MESSAGE_OPERATION command, 
69, 217, 221 

MIDI devices, playing, 213-14 
MIDI file formats, 112 
MIDI standard, 211-13 
MIDI standard presentation 
header, 112 

MMAUDIOHEADER, 111, 121 
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MMBASE environmental 
variable, 315 
MMFORMATINFO data 
structure, 80, 93-95 
MMIMAGEHEADER, 111 
MMINIFILEINFO data 
structure, 80, 88 

MMIO (Multimedia Input/Output), 
6-7, 12 

services provided by, 20-21 
mmioAdvance API, 108 
MMIO_ALLOCBUF flag, 106, 108 
mmioAscend API, 102 
mmioCFAddElement API, 152 
mmioCFAddEntry API, 151 
mmioCFChangeEntry API, 151 
mmioCFClose API, 151 
mmioCFCompact API, 152 
mmioCFCopy API, 152 
mmioCFDeleteEntry API, 152 
MMIO_CF_FAILURE, 77 
mmioCFFindElement API, 152 
mmioCFFindEntry API, 151 
mmioCFGetlnfo API, 78, 151 
mmioCFOpen API, 78, 151 
mmioCFRemoveElement API, 152 
mmioCFSetlnfo API, 151 
mmioClose API, 105 
mmioCreateChunk API, 102 
mmioDescend API, 102 
mmioDetermineSSIOProc API, 149 
MMIO_ERROR, 77 
MMIOERR_UNSUPPORTED_ 
MESSAGE, 147 
mmioFindElement API, 74 
mmioFlush API, 108 
mmioGetData API, 77 
mmioGetFormatName API, 94 
mmioGetFormats API, 80, 90, 93, 
94-95 


mmioGetHeader API, 109 
with digital video devices, 230 
mmioGetlnfo API, 108 
mmioGetLastError API, 77-78 
mmioIdentifyFile API, 81 
mmioIdentifyStorageSystem API, 149 
MMIOINFO data structure, 74, 77 
mmioIniFileCODEC API, 164, 167, 

168 

mmioIniFileHandler API, 80, 83, 

88, 90 

mmioInstalllOProc API, 83, 85-86 
MMIO_INVISIBLE_FRAME flag, 136 
MMIO IO procedures. 

See I/O procedures 
MMIO_IS_KEY_FRAME flag, 135 
MMIO_IS_PALETTE flag, 136 
mmioLoadCODECProc API, 165 
MMIOJVLATCHCAPSFLAGS flag, 167 
MMIO_MATCHCOMPRESSSUBTYPE 
flag, 167 

MMIO.MATCHCOMPRESSTYPE 
flag, 167 

MMIO_MATCHDLL flag, 167 
MMIO_MATCHFOURCC flag, 167 
MMIO_MATCHHWID flag, 167 
MMIO_MATCHPROCEDURENAME 
flag, 168 

MMIOM_BEGININSERT 
message, 147 

MMIOM_BEGINRECORD 
message, 147 

MMIOM_BEGIN STREAM 
messages, 156, 158 
MMIOM_CLEAR message, 147 
MMIOM_CODEC_CLOSE 
messages, 166 

MMIOM_CODEC_COMPRESS 
messages, 166 
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MMIOM_CODEC_DECOMPRESS 
messages, 166 

MMIOM_CODEC_OPEN messages, 
165, 166 

MMIOM_CODEC_QUERYNAME 
LENGTH messages, 166 
MMIOM_CODEC_QUERYNAME 
messages, 166 

MMIOM_COMPRESS messages, 136, 
146, 161 

MMIOM_COPY message, 147 
MMIOM_CUT message, 147 
MMIOM_DECOMPRESS messages, 
135,146, 161 

MMIOM_DELETE message, 147 
MMIO_MEDIATYPE_AUDIO, 111, 
116 

MMIO_MEDIATYPE_ 

DIGITALVIDEO, 113, 116 
MMIO_MEDIATYPE_IMAGE, 

110, 116 

MMIO_MEDIATYPE_MIDI, 112, 116 
MMIO_MEDIATYPE_MOVIE, 

112, 116 

MMIOM_ENDINSERT message, 147 
MMIOM_ENDRECORD message, 148 
MMIOM_ENDSTREAM messages, 
156, 158 

MMIOM_messages, 74 
MMIOM_MULTITRACKREAD 

messages, 75, 101, 121, 127-33, 
135-36, 139 

MMIOM_MULTITRACKWRITE 
messages, 101, 121, 127, 133-36 
MMIOM_PASTE message, 148 
MMIOM_QUERYHEADERLENGTH 
messages, 101 

MMIOM_READ messages, 75, 76 
MMIOM_REDO message, 148 


MMIOM_SAVE message, 148 
MMIOM_SEEKBYTIME messages, 
137, 138 

MMIOM_STATUS message, 148 
MMIOM_TEMPCHANGE message, 
148 

MMIOM_UNDO message, 148 
MMIOM_WINMSG message, 148 
MMIO_NOIDENTIFY flag, 82 
MMIO_NORMAL_READ mode, 140 
MMIO_NOTRANSLATE flag, 109, 116 
MMIO_NULL_FRAME flag, 136 
mmioOpen API, 74, 77, 81-83, 84, 100 
for buffered I/O operations, 108 
with digital video devices, 230 
opening files with, 104-105 
opening memory files with, 106 
mmioQueryCODECName API, 168 
mmioQueryCODECN ameLength 
API, 168 

mmioQueryFormatCounty API, 94-95 
mmioQueryHeaderLength API, 109 
mmioRead API, 75, 76, 136-37 
mmioRemoveElement API, 74 
MMIO_REVERSE_READ mode, 140 
MMIO_SCAN_READ mode, 140 
mmioSeek API, 137 
mmioSendMessage API, 74, 75 
mmioSet API, 139-41 

associating CODECs with video 
tracks and, 141-46 
mmioSetBuffer API, 108 
mmioSetHeader API, 109 
mmioSetlnfo API, 108 
mmioStringToFOURCC API, 80 
MMIO (Multimedia Input/Output) 
subsystem, 71-172 
architecture of, 72-77 
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querying error information 
in, 77-78 

MMI 0_TRAN SLATED ATA flag, 109, 
116 

MMIO_TRANSLATEHEADER 
flag, 109 

mmioWrite API, 136-37 
MM_MCICUEPOINT messages, 66, 
70, 222 

MM_MCINOTIFY message, 25 
MM_MCIPOSITIONCHANGE 
messages, 65-66 
MMMIDIHEADER, 112 
MMMOVIEHEADER, 113 
MMMULTITRACKREAD data 
structure, 128-130 
MMMULTITRACKWRITE data 
structure, 133-134 
MMPM/2, 4, 12 

components of, 17-24 

MCI (Media Control Interface), 
17-19 

MMIO (Multimedia Input/ 
Output), 20-21 
MMPM/2 devices, 19-20 
SSM (Synchronization/Streaming 
Manager), 21-24 
detecting installation of, 315-16 
development environment for, 27-30 
general programming tips, 320-23 
application stack size, 320 
compile options for 
optimization, 323 
file handles, 321-22 
multithreaded applications, 320 
non-multimedia applications 
running in the background, 322 
performance tips, 320-21 


playing audio and movie files 
from a network server, 322 
single-spin vs. multi-spin 
CD-ROM drives, 322-23 
interfacing with, 345-60 
memory usage, 323-25 
multimedia controls provided by, 24 
programming model of, 25-27 
system architecture of, 15-17 
system usage considerations, 

325-30 

MMPMCD.INI file, 291-93 
MMPM/2 devices, 19-20 
MMPM2.INI, 54-58 
MMPM2.LIB, 29 
MMPMMMIO.INI, 80, 81, 88 
CODEC procedures in, 164, 165 
MMPM/2 toolkit, 27-28 
MMSTREAM environmental variable, 
324-25 

MMTIME units, 65, 195, 196, 197, 211 
MMVIDEOHEADER, 113, 121 
mode keyword, with status command, 
252 

monitoring a video capture, 276-77 
monitor keyword 

with set command, 256 
with status command, 253 
monitor window handle keyword 
combination, with status 
command, 253 
movie file formats. 

See also AVI movie file format 
data translation, 116-17 
digital video devices and, 229-30 
movie files. See also digital video; 
digital video devices 
read mode for, 139-40 
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movie standard presentation 
header, 112 
MPEG file format, 270 
MSV_SYSQOSERRORFLAG 
variable, 158 

MSV_SYSQOSVALUE variable, 158 
MSV_WORKPATH value, 318 
multimedia, definition of, 1-2 
multimedia controls, 24 
Multimedia Setup Applet, 234 
multiple track files, 94, 120-36 
headers of, 120-27 
messages used with, 127 
read operations with, 128-33 
seeking operations with, 139 
write operations with, 133-35 
multithreaded applications, 320 
MULTITRACKREADJEXTENDED 
flag, 128 

MULTITRACKWRITE_MERGE bit 
flag, 134-135 

mute button control, 310-12 

N 


natural computing, 2 
NEATSTUF directory, 30 
network server, playing audio and 
movie files from a, 322 
NOP_OPERATION command, 69, 217 
normal rate keyword combination, 
with status command, 252 
notify keyword or flag, 43-44, 316 
number of tracks keyword combina¬ 
tion, with status command, 252 


o 


open command, 5, 42-43 

for digital video capture devices, 
274 

with digital video devices, 235-36 
with waveaudio devices, 184-86, 
191 

opening files, 104-5 
memory files, 106-7 
open message, 18 

OS/2, 23-bit flat addressing memory 
model of, 15 

OS/2 Video IN. See Video IN 
OS2ME.H, 28 
oversampling, 177 
owner notifications, graphic buttons 
and, 302-3 

P 


panning, 177 
paste command, 52, 53 
for movies, 261 
for recordings, 208, 209 
paste keyword, with status 
command, 252 
pause command 
for movies, 248 
for waveaudio devices, 198 
PCM (Pulse Coded Modulation), 178 
PDDs (Physical Device Drivers), 19 
percentage keyword, with set 
command, 255 
performance tips, 320-21 
play button control, 309-10 
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play command 

for movies, 245-46, 262 
for waveaudio devices, 192-94 
playlist instructions, 67-70 
playlist record structure, 67 
playlists, 217-23 

commands supported by, 217, 
220-23 

PlayRec application, 331-62. See also 
sample multimedia application 
building and testing, 360-61 
PLAYER mode, 332 
RECORDER mode, 331-32 
using, 331-32 

polling vs. interrupt driven secondary 
storage device drivers, 329-30 
positionadvise events, for digital video 
devices, 250-51 

positionadvise messages, CD audio 
devices and, 294 
position keyword, with status 
command, 252 
PowerPC, 13 

presentation headers, 108-15 
audio, 111 
image, 110-11 

Presentation Manager, 25, 26 
procedural interface, string interface 
vs., 316 

programming languages, 11 
programming tools, 11 
Prominare Designer, 374 
P2STRING, 30 
pszCommand, 33 
pszReturnString:, 34 
Pulse Coded Modulation (PCM), 178 
put command, 260 


put record destination at 
command, 276 

put record source at command, 276 

Q 


quality of service network storage 
system, 156-61 

R 


RAW video data, 268, 282 
read mode, setting, 139, 140 
readonly flag, 321 
read operations, 136-37 

with multiple track files, 128-33 
ready keyword, with status 
command, 252 

record audio keyword combination 
with set command, 256 
with status command, 253 
record command 

for digital video capture devices, 
274-75 

digitalvideo device, 272 
for video captures, 279 
recording audio, 200-211 

compression types and, 202-4 
gain level for, 204-5 
simple, 205 
user-driven, 206-7 
RECORDTAB flags, video frame 
specific, 135-136 
RECORDTAB WRITE data 
structure, 135 
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redo command, 51 
for movies, 261 
for recordings, 210 
redo keyword, with status 
command, 252 

reference frame interval keyword 
combination, 
with set command, 257 
with status command, 253 
release command, 49 

for waveaudio devices, 186-87 
required commands, 5 
resource IDs, 337-39 
resource management, 46-49 
resume command 
for movies, 248 
for waveaudio devices, 198 
RETURN_OPERATION command, 
69, 217, 223 

reverse keyword, with play 
command, 245 

rewind command, for movies, 249 
REXX 

command files, 38-39 
multimedia functions, 37-39 
RIFF (Resource Interchange File 
Format), 6, 101-2 
APIs for, 102 

compound files and, 150-51 

s 


sample multimedia application, 
331-62 

building and testing, 360-61 
coding, 339-45 
dialogs in, 333-35 
look and feel of, 332-33 


menus in, 335-36 
resource IDs in, 337-39 
user interface in, 339, 342-43 
samplespersec keyword 
with set command, 256 
with status command, 253 
samples per second (SPS), 178 
sampling, 175 
sampling rate, 175 
saturation keyword 
with set command, 257 
with status command, 253 
save command 

for movies, 261, 262 
for video captures, 279 
saving, a recording, 206 
scalability, video playback, 232-33 
scan keyword, with play 
command, 245 
SCSI devices, 327-29 
secondary windows, 24, 300. See also 
window controls 
sample, 307-13 
seek command 
for movies, 249-50 
with waveaudio devices, 197 
seeking operations, 137-39 
with multiple track files, 139 
time vs. byte seeking, 138-39 
translated vs. untranslated, 139 
sequencer, 190, 213-14 
SERVICEJtEQUEST parameter, 
157,158 
set command 

for digital video capture devices, 
275-76 

for digital video devices, 254-57 
for time formats, 196 
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setcuepoint command, 66, 194, 196- 
97, 221-222, 250, 318 
set monitor on command, 276 
setpositionadvise command, 64-65, 
250 

frequency of, 317-18 
with waveaudio devices, 194-97 
settuner command, 284 
sharing states, 46-47 
sharpness keyword 
with set command, 257 
with status command, 253 
signal aliasing, 176 
simple devices, 5 
slow keyword, with play 
command, 245 

Software Motion Video (SMV), 7-8, 
12-13 

Software Video Recorder, 271 
sound, nature of, 174-75 
sound cards, 3 

SPCBs (stream protocol control 
blocks), 23 

speed command, with play 
command, 246 

speed format keyword combination 
with status command, 252 
speed keyword, with status 
command, 252 

SPS (samples per second), 178 
SSM (Synchronization/Streaming 
Manager), 21-24, 182 
status command, 50-51 

for digital video devices, 251-54 
for waveaudio devices, 199 
status droppedframepct 
command, 264 

status position command, 262 


step command, for displaying video 
frames, 246 
stereo, 177 
stop command 
for movies, 248 
for recording audio, 206 
for waveaudio devices, 198 
storage system I/O procedures, 73, 
149-61 

DOS and MEM storage systems, 
149-50 

stream handlers, 22 
streaming, 289-91 

string interface, procedural interface 
vs., 316 

subsystem development, 26-27 
super VGA modes, 226 
synchronization, 23 

audio and video, 263-65 
for movie files, 64-66 
synchronous command execution 
mode, 43 

synchronous mode, 26 
sysinfo command, 54, 58 
system aliases, 40-41 
system commands, 5 
System Exclusive (SysEx) 
message, 212 
system values, 63-70 
querying, 64 

T 


table of contents, of CD audio discs, 
295-96 

time format frames keyword combina¬ 
tion, with set command, 255 
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time format hmsf keyword combina¬ 
tion, with set command, 255 
time format hms keyword combina¬ 
tion, with set command, 255 
time format keyword combination, 
with status command, 252 
time format mmtime keyword 
combination, with set 
command, 255 

time format ms keyword combination, 
with set command, 255 
time formats, audio-related, 195-96 
timing events, with waveaudio 
devices, 194-95 
TRACKMAP array, 134, 135 
translation, 115-20 
transparent color keyword combina¬ 
tion with set command, 257 
with status command, 253 
TV signal, displaying a, 283-84 
TV tuner, 283-84 
two-state buttons, 304-5 

u 


Ultimedia Tools Series, 375-76 
Ultimotion 

compression and decompression 
with, 269 

no-cost license, 376-77 
undo command, 51 
for movies, 261 
for recordings, 210 
undo keyword, with status 
command, 252 

UPC (Universal Product Code), for 
CD audio discs, 297 


user interface, 339, 342-43 

V 


vertical image extent keyword combi¬ 
nation, with status command, 252 
vertical video extent keyword 
combination, with status 
command, 253 
VGA mode, 226 
video capture. See digital video 
capture 

video capture adapters, 365-71 
video compression keyword 
combination, 
with set command, 257 
with status command, 254 
video compression subtype keyword 
combination, 
with set command, 257 
with status command, 254 
video frames, RECORDTAB flags 
for, 135-36 

Video IN, 8, 72, 234, 271 
video quality keyword combination 
with set command, 257 
with status command, 254 
video record frame duration keyword 
combination, 
with set command, 257 
with status command, 254 
video record rate keyword 
combination, 
with set command, 257 
with status command, 254 
video resolution, scalability of, 232 
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video standard presentation 
header, 113 

video tracks, associating CODECs 
with, 141-46 
volume 

compact disc audio, 293-94 
of waveaudio devices, 198-99 
volume keyword 

with set command, 256 
with status command, 253 
VSD (Vendor Specific Device), 19, 
284-85 

w 


wait keyword, 316 
waveaudio (waveform audio), 8, 
173-223 

analog signal to digital data 
relationship, 175-78 
data types, formats and storage, 
178-80 

playing back, 182-200. See also 
playlists 

acquire and release commands, 
186-87 

cueing the waveaudio device, 192 
determining what devices are 
available, 183-84 
device capabilities, 188-90 
device IDs, 187-88 
loading audio files, 190-92 
media position, 199 
MIDI, 213-14 

opening waveaudio devices, 
184-86 


pause, resume and stop 
commands, 198 
play command, 192-94 
seeking during, 197 
sharing modes and device 
ownership, 186-88 
simple playback, 199-200 
time formats and tracking 
playback,194-97 
volume, 198-99 

recording, 174, 200-211. See also 
playlists 

compression types, 202-4 
conversational speech, 180 
cut, copy and paste commands, 
208-9 

delete command, 210-11 
editing operations, 208-9 
format tags and, 202-4 
gain, 204-5 

MIDI standard, 211-13 
saving the recording, 206 
simple recording, 205 
undo and redo commands, 210 
user-driven recording, 206-7 
waveaudio devices, 5 

capability command for, 188-90 
connections for, 214-17 
cueing, 192 

determining availability of, 183-84 
IDs of, 187-88 
opening, 184-86, 191 
type definitions for, 189-90 
WAVEDOC, 30 

waveform audio. See waveaudio 
(waveform audio) 
where command, 260 
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window(s) 

application-supplied, 259-60 
default, 258-59 
window command, 260 
for digital video capture 
devices, 277 

window controls, 299-313 
circular sliders, 305-6 
graphic buttons, 300-304 
sample, 307-13 

window handle default command, 259 
window handle keyword combination, 
with status command, 253 
window management commands, 260 
window state show command, 262 
WinOS2, 325-27 

multimedia support under, 325-26 
program object settings, 326-27 
WinTV adapter, 283-84 
write operations, 136-37 

with multiple track files, 133-35 
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